Z User
7acc0c5451
5 PRD gaps fixed: 1. Zod validation on all API inputs (§5.2) — 26 files, 27 safeParse 2. Rate limiting on public endpoints (§5.6) — 6 scopes, 7 endpoints 3. Custom fields JSONB with schema (§5.5) — 2 models, 10 seed defs 4. CSP + security headers (§5.6) — 7 headers via next.config.ts 5. ESLint module boundary rule (§5.4) — no-restricted-imports 0 TS errors, ESLint clean.
133 lines
4.1 KiB
Markdown
Executable File
133 lines
4.1 KiB
Markdown
Executable File
# 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.
|