# 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.

## Tech Stack
- **Framework**: Next.js 16 (App Router, Turbopack)
- **Language**: TypeScript 5 (strict)
- **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)

## 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
```

## Architecture
- **Single deployable** (modular monolith per PRD D1)
- **Money**: integer cents, tax in basis points. No floats.
- **GoBD**: immutable after Festschreibung, corrections via Storno (new row)
- **Audit**: hash-chain on all business operations
- **Auth**: Bearer token (SHA-256 hashed at rest) with scoped permissions

## 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
```

## 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`

## 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)

## Important Rules
- No mocks in production code — 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)
- Client Portal: no agency-internal details visible to clients
- German UI by default (i18n: DE/EN/TR)