Z User
7acc0c5451
5 PRD gaps fixed: 1. Zod validation on all API inputs (§5.2) — 26 files, 27 safeParse 2. Rate limiting on public endpoints (§5.6) — 6 scopes, 7 endpoints 3. Custom fields JSONB with schema (§5.5) — 2 models, 10 seed defs 4. CSP + security headers (§5.6) — 7 headers via next.config.ts 5. ESLint module boundary rule (§5.4) — no-restricted-imports 0 TS errors, ESLint clean.
135 lines
6.0 KiB
Markdown
Executable File
135 lines
6.0 KiB
Markdown
Executable File
# AOS — Agency Operating System
|
|
|
|
## Project Overview
|
|
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, 0 errors)
|
|
- **Database**: Prisma ORM (SQLite for dev)
|
|
- **UI**: shadcn/ui + Tailwind CSS 4 (monochrome design)
|
|
- **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 with realistic data
|
|
```
|
|
|
|
## Architecture
|
|
- **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**: 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 (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 (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), 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 — real implementations only
|
|
- No `any` types — all interfaces explicitly typed
|
|
- 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.
|