Files

T

hwinkel 1ffbcf237c chore: update .gitignore to include graphify-out directory and add copilot instructions

2026-04-13 21:50:41 +02:00

14 KiB

Raw Blame History

Copilot Instructions for Annas Rechnungsmanager

Project: German accounting & invoice management system for tax consultants
Tech Stack: React Router v7, TypeScript, Prisma, MariaDB, Tailwind CSS v4, Docker
Language: English for code/comments, German for business logic and docs

Quick Start for Copilot

1. Setup & Environment

Before making any changes, ensure the environment is ready:

npm install                    # Install dependencies
cp .env.example .env           # Create .env from example
npx prisma migrate deploy      # Apply database migrations
npm run db:seed               # Seed initial data (optional)
npm run dev                   # Start dev server on http://localhost:5173

Database: Requires MariaDB 10.5+ (or MySQL 8.0+). Can run via Docker:

docker-compose up -d          # Starts MariaDB, Redis (if configured)

2. Codebase Map

app/ — React Router v7 (file-based routing, SSR)
- routes/ — Page routes + API endpoints (REST)
- components/ — Shared UI (shadcn/ui + Tailwind)
- lib/ — Business logic, DB queries, utils
- session.server.ts — Auth & cookie sessions
prisma/ — Database schema, migrations, seed script
scripts/ — CLI helpers (setup-admin, reset-password)
public/ — Static assets (SVGs, images)
graphify-out/ — Knowledge graph (visual map of code - see GRAPH_REPORT.md)

3. Key Files to Know

File	Purpose
`prisma/schema.prisma`	Data model (Users, Companies, Invoices, Customers, etc.)
`app/root.tsx`	Root layout, error boundaries, global styles
`app/entry.server.tsx`	Server-side rendering entry
`app/session.server.ts`	Auth logic, session management
`app/lib/tax.ts`	German tax calculations (USt, AFA)
`app/lib/prisma.server.ts`	DB client initialization

Development Workflows

Adding a New Feature

Understand the domain: Read CLAUDE.md section 1 (project overview)
Find the god node: Check graphify-out/GRAPH_REPORT.md for related files
Implement in layers:
- Add schema to prisma/schema.prisma → npx prisma migrate dev
- Create API endpoint in app/routes/api.*
- Create UI route in app/routes/
- Add business logic to app/lib/
Test: npm run typecheck && npm run lint && npm run test (if tests exist)
Verify in dev: npm run dev → test manually in browser

Editing Existing Routes/Components

Routes use file-based routing: app/routes/companies.$id.tsx → /companies/123
Nested routes: app/routes/companies.$id.invoices.tsx → /companies/123/invoices
API routes: app/routes/api.invoices.ts → POST /api/invoices
Use loader for GET data, action for POST/PUT/DELETE (Remix/React Router pattern)

Database Changes

# Make changes to prisma/schema.prisma, then:
npx prisma migrate dev --name description  # Creates migration + applies it
npx prisma studio                          # GUI browser for data

Authentication

Sessions stored in browser cookies (signed, httpOnly)
Check app/session.server.ts for session helpers
Protect routes with requireAuth() or check session in loader
Passwords hashed with bcryptjs

Code Style & Conventions

TypeScript

Strict mode enabled (strict: true in tsconfig.json)
Use unknown for external data, then guard with type checks
Don't use any — use unknown + assertion if needed
Nullable types: prefer explicit | null over optional ?

React Router v7

Use loaders for data fetching (server-side)
Use actions for mutations
Return redirect(), json(), or React components from loaders
Use <Form> instead of <form> for proper handling

Database Queries

Use Prisma (never raw SQL in business code)
Keep queries in app/lib/ (not in components or routes)
Example: app/lib/invoices.ts exports getInvoiceById(), createInvoice(), etc.

UI Components

Use shadcn/ui components (in app/components/ui/)
Style with Tailwind CSS v4 utility classes
Keep components small, prefer composition over props drilling
Use <Card>, <Button>, <Dialog>, <Select>, <Input> from shadcn

Naming

Components: PascalCase (InvoiceForm.tsx)
Utilities/functions: camelCase (calculateTax())
Constants: UPPER_SNAKE_CASE (INVOICE_STATUSES)
CSS classes: kebab-case (Tailwind default)
Database tables: singular, lowercase (user, invoice, company)

Business Logic (Important!)

German Tax (Umsatzsteuer)

§14 UStG: Invoice compliance required for VAT
Tax calculations in app/lib/tax.ts
Net/Gross amounts: always track both
Tax rates: 19% (standard), 7% (reduced), 0% (exports)

Invoice Numbering

Must be sequential and unique per company
Logic in app/lib/invoice-number.server.ts
Stored in database to prevent duplicates

Expense/Income Categories

Stored in database (user-configurable per company)
Used for reports and tax deductions
Budget constraints apply (see schema)

Audit Logging

Every write operation must log to audit table
Include user ID, IP, timestamp, action type
Check app/lib/logger.server.ts

Testing & Validation

Type Checking

npm run typecheck  # Runs tsc --noEmit (catches type errors)

Always run before committing. This is non-negotiable.

Linting (if configured)

npm run lint       # Runs eslint
npm run lint:fix   # Auto-fixes style issues

Manual Testing

npm run dev
# Test in browser at http://localhost:5173
# Try happy path + error cases

Database Validation

Prisma will catch schema errors on migration
Use prisma studio to verify data after changes
Test with sample data (seed script)

Common Gotchas & Constraints

❌ Don't

Don't import from routes into components — causes circular deps
Don't fetch data in components — use loaders instead
Don't store sensitive data in cookies (sessions are signed, but still)
Don't modify prisma/schema.prisma without a migration
Don't skip npm run typecheck — type errors hide bugs
Don't commit with unresolved TypeScript errors

✅ Do

Use server-side rendering for auth, tax calculations, sensitive data
Keep server logic in app/lib/, not in routes
Use Prisma transactions for multi-step operations (invoices + payments)
Validate user input on both client (UX) and server (security)
Log important actions (invoice created, payment received, user deleted)
Test edge cases (negative amounts, invalid dates, permission checks)

Session Management

Sessions expire after inactivity (see .env for timeout)
Check session in every protected route's loader
Use destroySession() on logout
Set secure: true for HTTPS (production only)

Deployment

Docker image builds from Dockerfile
docker-compose.yml for local dev (MariaDB + app)
Never commit .env or secrets — use .env.example as template
Migrations run automatically on container start (see Dockerfile)

How to Ask Copilot for Help

Effective Requests

✅ Good:

"Add a new invoice status 'draft' to the system. Update schema, create API endpoint, update UI."
"The tax calculation is wrong for exports (0% VAT). Where is this logic?"
"Refactor InvoiceForm to use Zod validation."

❌ Vague:

"Make it work better"
"Fix the database"
"Add a feature"

Before Asking

Read CLAUDE.md — covers project context, architecture, key files
Check the graph — graphify-out/GRAPH_REPORT.md shows component relationships
Look at similar code — find a similar feature and adapt
Run typecheck — make sure your environment is valid

When Stuck

Describe the feature + why you're stuck
Paste error messages (full stack trace)
Mention which file/function you're working in
Explain what you tried

Environment Setup

Required

Node.js 22+ — check with node --version
npm 10+ — check with npm --version
MariaDB 10.5+ (local or Docker) — check with mysql --version

Optional

Docker — for containerized MariaDB + app
Prisma Studio — GUI for database: npx prisma studio
VS Code + TypeScript extension — for type hints while coding

.env Template

DATABASE_URL="mysql://root:password@localhost:3306/annas_rechnungsmanager"
NODE_ENV="development"
ADMIN_PASSWORD="admin"  # Initial admin password
SESSION_SECRET="your-secret-key-here"  # Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Useful Commands

Command	Purpose
`npm run dev`	Start dev server with hot reload
`npm run typecheck`	Type-check without building
`npm run lint`	Run ESLint
`npm run build`	Build for production
`npm run db:seed`	Seed database with sample data
`npx prisma studio`	GUI for database
`npx prisma migrate dev`	Create + apply migration
`npx prisma migrate reset`	⚠️ Wipe DB + re-seed (dev only!)
`npm run setup-admin`	Create admin user (or use Docker env var)

Knowledge Graph & Architecture Visualization

A comprehensive visual map of this codebase exists in graphify-out/. This is your architectural compass — use it before diving into features.

Files Generated

graph.html — Interactive D3.js visualization (275 nodes, 590 edges, 100 communities)
graph.json — Raw graph data (importable into Neo4j, Obsidian, etc.)
GRAPH_REPORT.md — Analysis report with hub nodes and surprising connections

How to Use It

1. Open the Visualization

open graphify-out/graph.html
# Or on Linux: xdg-open graphify-out/graph.html

Drag nodes to explore relationships
Hover to highlight connections
Sidebar shows: god nodes, key insights, legend by file type

2. Read the Report

cat graphify-out/GRAPH_REPORT.md

Contains:

God Nodes — Most connected files (hub architecture)
- companies.$id.invoices.$invoiceId.tsx (8 connections) — Invoice editing is central
- session.server.ts (7 connections) — Auth touches everything
- afa.ts (6 connections) — Tax/depreciation widely used
Surprising Connections — Cross-file bridges you didn't expect
Suggested Questions — Pre-built exploration angles

3. Answer Specific Questions

Before implementing a feature, ask the graph:

"How do invoice routes connect to pricing?"

graphify query "invoice routes pricing"
# Returns: node paths, edge types, confidence scores

"What's the shortest path from InvoiceForm to TaxCalculation?"

graphify path "InvoiceForm" "TaxCalculation"
# Returns: dependency chain with edge types (imports, calls, etc.)

"Tell me everything about session.server.ts"

graphify explain "session.server.ts"
# Returns: node info, all connections (incoming/outgoing), file location

Common Use Cases

🔍 Understanding a New Area

Open graph.html
Search the visualization for relevant keywords (invoice, tax, payment)
Click god nodes to see what's connected
Run /graphify query on a concept you don't understand

Before editing a file, check what it connects to:

graphify explain "companies.$id.invoices.tsx"
# See: what imports it, what it imports, data flow

🚨 Impact Analysis Before Changes

Need to modify session.server.ts?

graphify query "session authentication routes"
# See all places that depend on auth logic
# Helps avoid breaking changes

🏗️ Refactoring with Confidence

When consolidating duplicate code:

graphify path "ExpenseCategory" "IncomeCategory"
# Find if they share logic or should be unified

Graph Legend

Symbol/Color	Meaning
🔵 Blue node	Code file (.ts, .tsx, .js)
🟢 Green node	Document (.md)
🟠 Orange node	Image/Asset (.svg, .png)
Solid edge	Direct relationship (import, call, cite)
Dashed edge	Inferred relationship (similar concepts)
Edge thickness	Confidence score (thicker = more confident)

God Nodes (Hub Architecture)

These 5 files are the system's backbone:

File	Connections	Why It Matters
`companies.$id.invoices.$invoiceId.tsx`	8	Invoice editing is core — touches pricing, payments, customers
`session.server.ts`	7	Authentication is pervasive — protects all private routes
`companies.$id.anlagevermoegen.tsx`	7	Asset management — deep dependency on tax logic
`afa.ts`	6	Depreciation calculations — used in reports, invoices, exports
`companies.$id.ausgaben.tsx`	6	Expense tracking — feeds into tax reports, budgets

Implication: Changes to these files have wide impact. Test thoroughly and check the graph for dependents.

Updating the Graph

When you add new files or features:

graphify --update
# Re-scans repo, only re-extracts changed files
# Merges with existing graph.json
# Updates GRAPH_REPORT.md automatically

Or full rebuild (slow, but thorough):

rm -rf graphify-out/*.json
graphify .

Integration with Development

Before a sprint: Open the graph, understand the domain
Before editing a file: Run graphify explain on it
Before refactoring: Check graphify query for impact
After big changes: Run graphify --update to keep it fresh
In code review: Reference the graph to explain architecture

Key Resources

CLAUDE.md — Project onboarding (read this first!)
README.md — User-facing project description
prisma/schema.prisma — Data model
graphify-out/ — Knowledge graph + visual architecture
Prisma docs: https://www.prisma.io/docs/
React Router v7 docs: https://reactrouter.com/
Tailwind CSS v4: https://tailwindcss.com/docs
shadcn/ui: https://ui.shadcn.com/

Questions?

If something is unclear:

Check CLAUDE.md first
Look at the knowledge graph
Find similar code in the codebase
Ask Copilot with as much context as possible

Good luck! 🚀

14 KiB Raw Blame History