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

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

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

```bash
# 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](./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

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