AOS — Agency Operating System

Self-hosted platform for German software agencies. Lead → Deal → Quote → Project → Invoice → License → Renewal. GoBD-compliant accounting (SKR04, EÜR, UStVA, DATEV). Client Portal. MCP Server for Claude Code.

Quick Start (Docker)

# 1. Clone
git clone https://github.com/cetinmustafa83/aos.git
cd aos

# 2. Configure
cp .env.example .env
# Edit .env: set ENCRYPTION_KEY, AUTH_SECRET (openssl rand -base64 32)

# 3. Build + Run
docker compose up -d

# 4. Seed (first time)
docker exec aos-app npx prisma db push --accept-data-loss
docker exec aos-app node -e "require('./src/lib/seed')" # or: docker exec aos-app bun run src/lib/seed.ts

# 5. Open
# https://localhost

Quick Start (Development)

# 1. Clone
git clone https://github.com/cetinmustafa83/aos.git
cd aos

# 2. Install
bun install

# 3. Database
bun run db:push
bun run src/lib/seed.ts

# 4. Start
bun run dev
# → http://localhost:3000

Claude Code / MCP

The .mcp.json at repo root enables auto-detection. After seeding, the pre-built admin token works:

# Seed creates the token automatically
bun run src/lib/seed.ts

# Token: aos_admin_seed_token_for_claude_code_2026
# 29 MCP tools (16 read + 13 write) — full agency management

See CLAUDE.md for the complete 29-tool reference with usage examples.

Architecture

aos/
  src/
    app/
      api/aos/         # 30+ internal API routes
      api/v1/          # Public REST API (scoped tokens)
      api/mcp/         # MCP Server (29 JSON-RPC tools)
      api/health/      # Health check
    components/aos/     # 23 views + client portal
    lib/               # Shared logic (db, format, i18n, api-auth, webhook)
  prisma/              # 39 models (SQLite dev, PostgreSQL prod)
  deploy/              # Docker, backup, restore scripts
  .mcp.json            # Claude Code auto-detection
  CLAUDE.md            # Project instructions + MCP reference
  Dockerfile           # Multi-stage production build
  docker-compose.yml   # app + backup + caddy

Modules

Module	Features
Dashboard	KPIs, pipeline funnel, onboarding checklist
CRM	Kanban pipeline, companies, persons, CSV import
Leads Finder	Evidence-based audits, AI explanation
Angebote	Quotes → accept → project → invoice
Projekte	Tasks, time tracking, budgets, task comments
Zeiterfassung	Weekly timesheet, PM lock (GoBD)
Support	Tickets, AI summary/reply, SLA timers
Lizenzen	Issued licenses + renewal register
Verträge	Werkvertrag, AVV, NDA, SLA, e-signature
Ausgaben	Billable, recurring, DATEV export
Finanzen	Invoices, E-Rechnung, gapless numbering
Wiederkehrend	Recurring invoice scheduler + license suspend
Buchhaltung	SKR04, UStVA, EÜR, Bankabgleich, Mahnwesen
Finanzamt	Belege, Pauschalen, Anlagen/AfA, Kassenbuch
Fristen	Unified deadline calendar (iCal feed)
Reporting	Pipeline, utilization, MRR/ARR
Wissensdatenbank	Versioned articles, AI drafting
API & Webhooks	Scoped tokens, HMAC webhooks, OpenAPI
Datenverwaltung	DSGVO Art. 15/20 export, Art. 30 inventory
Client Portal	Project-scoped, approvals with IP evidence
Einstellungen	Typed settings, i18n (DE/EN/TR)
Setup-Wizard	7-step guided installer

Compliance (Germany/EU)

• GoBD: Festschreibung (SHA-256 hash chain), 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: Doppelte Buchführung, Saldenliste, DATEV EXTF export
• UStVA: Kennzahlen 81/86/66/83/65/37, ELSTER XML
• AfA: GWG (§ 6 Abs. 2), Sammelposten (§ 6 Abs. 2a), lineare AfA (§ 7)
• Kassenbuch: § 146 AO, § 22 UStG
• Pauschalen: EStG § 4 Abs. 5, § 9 Abs. 1

Backup & Restore

# Backup (creates timestamped .db + .sha256)
./deploy/backup.sh

# Restore (verifies checksum, backs up current DB)
./deploy/restore.sh /path/to/aos_20261027_030000.db

Docker backup runs automatically daily at 03:00.

License

Proprietary. © Nordlicht Digital GmbH.