Z User
ab9fd10b5e
Claude Code integration: - .mcp.json at repo root for auto-detection (uses seed admin token) - CLAUDE.md project instructions (commands, architecture, rules) - Pre-seeded admin token: aos_admin_seed_token_for_claude_code_2026 - Scopes: all read + all write + mcp:read + mcp:write - Works out of the box after bun run src/lib/seed.ts 5 new MCP read tools (20 total: 11 read + 9 write): - get_buchhaltung: SKR04 Konten, Journal, Saldenliste, EÜR summary - get_anlagen: Anlagenverzeichnis with AfA, book values, GWG - get_kassenbuch: Cash book entries, running balance - get_belege: Receipts with SHA-256 content hashes - get_finanzamt: VAT returns, Jahreserklärungen, Jahresarchive Fix: api-auth regex updated to allow underscores in tokens (aos_[a-z0-9_]+) Health endpoint: GET /api/health (DB connection + version + uptime)
60 lines
2.3 KiB
Markdown
60 lines
2.3 KiB
Markdown
# 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)
|