diff --git a/CLAUDE.md b/CLAUDE.md index aafa749..32a6efa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,59 +1,134 @@ # AOS — Agency Operating System ## Project Overview -Self-hosted platform for German software agencies. CRM, Leads Finder, Projects, Licenses, Contracts, Expenses, Finance, full Accounting (SKR04, GoBD, ELSTER, DATEV), Client Portal, MCP Server, PWA. +Self-hosted platform for German software agencies. Full lifecycle: Lead → Deal → Quote → Project → Invoice → License → Renewal. GoBD-compliant accounting (SKR04, EÜR, UStVA, DATEV). Client Portal. MCP Server for Claude Code. ## Tech Stack - **Framework**: Next.js 16 (App Router, Turbopack) -- **Language**: TypeScript 5 (strict) +- **Language**: TypeScript 5 (strict, 0 errors) - **Database**: Prisma ORM (SQLite for dev) - **UI**: shadcn/ui + Tailwind CSS 4 (monochrome design) -- **State**: Zustand + TanStack Query patterns -- **AI**: z-ai-web-dev-sdk (server-side only) +- **State**: Zustand + custom useFetch hook +- **AI**: z-ai-web-dev-sdk (server-side only, 3 AI flows) +- **i18n**: DE/EN/TR ## Commands ```bash -bun run dev # Start dev server (port 3000) -bun run lint # ESLint check -bun run db:push # Push Prisma schema to DB -bun run db:generate # Generate Prisma Client -bun run src/lib/seed.ts # Seed database +bun run dev # Start dev server (port 3000) +bun run lint # ESLint check +bun run db:push # Push Prisma schema to DB +bun run db:generate # Generate Prisma Client +bun run src/lib/seed.ts # Seed database with realistic data ``` ## Architecture -- **Single deployable** (modular monolith per PRD D1) -- **Money**: integer cents, tax in basis points. No floats. +- **Modular monolith** — one deployable, strict module boundaries +- **Money**: integer cents, tax in basis points (1900 = 19%). No floats. - **GoBD**: immutable after Festschreibung, corrections via Storno (new row) -- **Audit**: hash-chain on all business operations +- **Audit**: SHA-256 hash-chain on all business operations - **Auth**: Bearer token (SHA-256 hashed at rest) with scoped permissions +- **No mocks** — real implementations only (TCP mail test, CAMT.053 parser, ELSTER XML) ## Key Directories ``` -src/app/api/aos/ # Internal API routes -src/app/api/v1/ # Public REST API (scoped tokens) -src/app/api/mcp/ # MCP Server (JSON-RPC for Claude Code) -src/components/aos/ # All UI components -src/lib/ # Shared logic (db, format, i18n, api-auth, webhook) -prisma/ # Schema + migrations +src/app/api/aos/ # Internal API (28+ endpoints) +src/app/api/v1/ # Public REST API (scoped tokens) +src/app/api/mcp/ # MCP Server (29 JSON-RPC tools) +src/app/api/health/ # Health check endpoint +src/components/aos/ # All UI components (23 views) +src/lib/ # Shared logic (db, format, i18n, api-auth, webhook) +prisma/ # Schema (30+ models) +.mcp.json # Claude Code auto-detection ``` -## MCP Server -- Endpoint: `POST /api/mcp` (JSON-RPC 2.0) -- 15 tools: 7 read + 8 write -- Auth: Bearer token with `mcp:read` or `mcp:write` scope -- All write actions audit-logged with actor `mcp-agent` +## MCP Server (29 Tools) + +Claude Code auto-detects `.mcp.json` and connects with the seed admin token. + +### Read Tools (16) +| Tool | Description | +|---|---| +| `search_companies` | Search CRM companies by name/city/website | +| `get_pipeline` | Sales pipeline deals by stage | +| `get_invoice` | Single invoice by number with E-Rechnung status | +| `list_leads` | Leads Finder queue with scores | +| `get_dashboard` | Agency KPIs (pipeline, MRR, projects) | +| `list_tickets` | Support tickets with SLA info | +| `get_buchhaltung` | SKR04 Konten, Journal, EÜR summary | +| `get_anlagen` | Anlagenverzeichnis with AfA depreciation | +| `get_kassenbuch` | Cash book entries, running balance | +| `get_belege` | Receipts with SHA-256 content hashes | +| `get_finanzamt` | VAT returns, Jahreserklärungen, Jahresarchive | +| `get_contracts` | Verträge (AVV, NDA, SLA, Werkvertrag) | +| `get_projects` | Projects with progress, budget, task counts | +| `get_timesheet` | Weekly timesheet grid with lock status | +| `get_notifications` | All alerts (overdue, expiring, SLA breaches) | +| `get_calendar` | Upcoming deadlines (30-day look-ahead) | + +### Write Tools (13) +| Tool | Description | +|---|---| +| `approve_lead` | Approve a lead in the review queue | +| `create_ticket` | Create a support ticket | +| `create_deal` | Create a deal with value/stage/probability | +| `update_deal_stage` | Move deal through pipeline | +| `create_task` | Create a task with priority/assignee/estimate | +| `log_time` | Log billable time with rate | +| `create_invoice` | Create draft invoice with line items | +| `finalize_invoice` | Lock + send invoice (GoBD Festschreibung) | +| `run_recurring` | Run recurring invoice scheduler + license suspend | +| `create_buchung` | SKR04 Buchungssatz (Soll an Haben) | +| `create_beleg` | Register receipt (SHA-256, GoBD retention) | +| `create_pauschale` | Homeoffice/Kilometer/Verpflegung (auto-computed) | +| `create_kassenbuch_entry` | Cash book entry (§ 146 AO, immutable) | + +### Usage Examples +```jsonc +// Search companies +{"name": "search_companies", "arguments": {"query": "Hamburg"}} + +// Create a deal +{"name": "create_deal", "arguments": {"companyId": "abc123", "title": "Website Relaunch", "valueCents": 980000, "stage": "proposal"}} + +// Log time +{"name": "log_time", "arguments": {"projectId": "xyz789", "description": "SSO integration", "minutes": 180, "rateCentsPerHour": 9500}} + +// Create invoice + finalize +{"name": "create_invoice", "arguments": {"companyId": "abc123", "lines": [{"description": "Website Audit", "quantity": 1, "unitCents": 45000}]}} +{"name": "finalize_invoice", "arguments": {"invoiceId": "inv123", "zugferd": true}} + +// Book a Buchungssatz (SKR04) +{"name": "create_buchung", "arguments": {"belegdatum": "2026-10-27", "sollKontoNummer": "4930", "habenKontoNummer": "1200", "betragCents": 89900, "buchungstext": "JetBrains Lizenz"}} + +// Create a Kilometerpauschale +{"name": "create_pauschale", "arguments": {"type": "kilometer", "date": "2026-10-27", "km": 140, "vehicleType": "auto", "description": "Kundentermin Berlin"}} +``` ## Compliance -- GoBD: Festschreibung (SHA-256 hash), immutable Buchungssätze, 8/6 year retention -- DSGVO: Art. 15/17/20/30, consent log, data export with checksum -- E-Rechnung: ZUGFeRD/XRechnung (EN 16931) -- SKR04 Kontenrahmen, EÜR, UStVA, DATEV EXTF export -- ELSTER: UStVA XML (ERiC requires cert in production) +- **GoBD**: Festschreibung (SHA-256), immutable Buchungssätze, 8/6 year retention +- **DSGVO**: Art. 15/17/20/30, consent log, data export with checksum +- **E-Rechnung**: ZUGFeRD/XRechnung (EN 16931) +- **SKR04**: Kontenrahmen, doppelte Buchführung, Saldenliste +- **EÜR**: Anlage EÜR with AVEÜR line numbers (§ 4 Abs. 3 EStG) +- **UStVA**: Kennzahlen 81/86/66/83/65/37, ELSTER XML +- **DATEV**: EXTF v5.0 Buchungsstapel export +- **AfA**: GWG (§ 6 Abs. 2), Sammelposten (§ 6 Abs. 2a), lineare AfA (§ 7) +- **Kassenbuch**: § 146 AO, § 22 UStG — immutable +- **Pauschalen**: EStG § 4 Abs. 5, § 9 Abs. 1 (Homeoffice, KM, Verpflegung) +- **Mahnwesen**: § 288 BGB Verzugszinsen, 3-stufig + license suspend ## Important Rules -- No mocks in production code — real implementations only +- No mocks — real implementations only - No `any` types — all interfaces explicitly typed -- All API routes have try/catch error handling -- All icon-only buttons have `aria-label` (WCAG 2.1 AA) +- All API routes: try/catch error handling +- All icon-only buttons: `aria-label` (WCAG 2.1 AA) - Client Portal: no agency-internal details visible to clients - German UI by default (i18n: DE/EN/TR) +- Money: cents (integer), tax: basis points. Never floats. + +## Seed Token +Pre-built admin MCP token for Claude Code: +``` +aos_admin_seed_token_for_claude_code_2026 +``` +Created by `bun run src/lib/seed.ts`. All read + write scopes. diff --git a/db/custom.db b/db/custom.db index 543fc3f..2ad47eb 100644 Binary files a/db/custom.db and b/db/custom.db differ