AOS/CLAUDE.md

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

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

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