00 – Architektur & Tech-Stack (Ist-Stand)

Tech-Stack

Schicht	Technologie
Framework	Next.js 15 (App Router, src/app), React 18, TypeScript 5
Auth	NextAuth 4 (Credentials), JWT-Sessions, bcryptjs
i18n	next-intl (de/en)
DB	PostgreSQL via pg (Pool), reine SQL-Migrationen (kein ORM)
Cache/Queue/PubSub	Redis (ioredis/redis), BullMQ für Agent-Jobs
AI	OpenAI SDK gegen Azure OpenAI (gpt-5-mini / gpt-4o-mini, Whisper/Transcription)
PDF	pdf-lib + HTML-Templates (src/templates/*.html)
Integrationen	googleapis (Calendar/Gmail), Microsoft Graph (Calendar/Mail), DocuSign (JWT), 360dialog (WhatsApp)
Storage	Azure Blob + per-Tenant OAuth (SharePoint/Drive/Dropbox/Nextcloud) – @work7/storage
Mail	Microsoft Graph (no-reply@work7.net)
Styling	Tailwind CSS, framer-motion, lucide-react
Validierung	Zod (v4)
Logging	pino

Monorepo-Struktur

Die App liegt unter work7_laendletech/src/ (npm-Workspaces). Wichtigste Ordner:

src/
├── src/app/         Next.js App Router – Seiten (UI) + API-Routes (/api/**)
├── src/components/  React-Komponenten (pro Feature-Ordner)
├── src/lib/         Feature-Logik im Web-Prozess (auth, time-entries, leave, calendar, …)
├── src/templates/   HTML-Vorlagen für PDF (Angebot, Rechnung, Rapport, AB)
├── packages/
│   ├── domain/      @work7/domain – gemeinsame Business-Logik + Tool-Registry (API & Agent)
│   ├── storage/     @work7/storage – Mandanten-Storage (Azure Blob, OAuth-Provider)
│   └── agent/       @work7/agent – WhatsApp-Agent (BullMQ-Worker, Capabilities, Azure OpenAI)
├── database/migrations/   nummerierte SQL-Migrationen (001…041)
├── deploy/chart/    Helm-Chart (Source of Truth fürs Deployment)
├── k8s/             Legacy-Manifeste (nur Fallback)
└── scripts/         start-all.js, dev-local, Tenant-/Storage-Tools

Laufzeit-Komponenten

Nach der Konsolidierung gibt es zwei Laufzeit-Prozesse plus DB/Redis:

• Next.js bedient Web-UI, REST-API, Webhooks und die Realtime-Bridge (SSE).
• Agent (@work7/agent) verarbeitet WhatsApp-Inbound + Reminder über BullMQ-Queues.
• Beide nutzen @work7/domain in-process → eine Business-Logik, identische Guards/Tenancy und identische Side-Effects (Notifications, Realtime). Siehe adr-0002-shared-domain-layer.
• Lokal/Helm startet scripts/start-all.js beide Prozesse (Next.js + Agent) gemeinsam und zusätzlich den Personalzeit-Cron-Runner (Auto-Close, siehe 08-zeiterfassung).

Landing/App-Surface-Split

Ein Image, aber zwei Rollen über Env WORK7_SURFACE (landing | app), durchgesetzt in src/middleware.ts + src/lib/site-surface.ts:

• landing → nur Marketing-Routen (/, /solutions, /loesungen, /resources, /impressum, /datenschutz) + /api/contact, /api/health. App-Pfade werden auf die App-Subdomain umgeleitet.
• app → SaaS + API; Root / rewritet auf den Login (/auth/signin).

Domains (Stand 2026-06-22): Prod work7.net / app.work7.net, Test test.work7.net / app.test.work7.net. Details in adr-0001-landing-app-domain-split.

Datenmodell – zentrale Tabellen

companies (Mandant, Key = company_id VARCHAR) ist die Tenancy-Wurzel; nahezu jede Tabelle trägt company_id. Kern-Entitäten:

• Identität/Mandant: companies, users, memberships, invites, onboarding_states, profiles, user_permissions, email_verification_tokens, notifications, audit_logs
• CRM/Projekt: kontakte (ex customers), organisation_personen, projects, project_personen, project_team, materials, documents
• Vertrieb/Rechnung: offers/offer_items, invoices/invoice_items/invoice_rapport_links/ invoice_counters/invoice_exports, labor_rates
• Ausführung: rapports/rapport_entries/rapport_materials, time_logs, positions
• Planung: appointments/appointment_assignments/appointment_status_history/ appointment_notifications, user_work_schedules, user_absences, appointment_conflicts
• Urlaub: leave_types/leave_policies/leave_balances/leave_requests/leave_approvals/ leave_request_events
• Sync/Storage: sync_connections/external_event_links/sync_events/sync_runs, tenant_storage_settings/tenant_storage_oauth_credentials/document_storage_mappings
• Agent/WhatsApp/AI: whatsapp_sessions/whatsapp_messages, agent_schedules/agent_media, ai_agent_memory/ai_audit, envelope_mappings (DocuSign)

Querschnitts-Konventionen

• API-Auth: requireSession(req) (src/lib/api-auth.ts) liefert { userId, role, companyId }; Webhooks/Cron nutzen Secret-/HMAC-/State-Validierung statt Session.
• Tenancy: jede Query ist auf company_id gescoped; Domain-Guards (requireTenantScope, requireRole) erzwingen das zentral.
• Rollen: 1 = Admin, 2 = Manager, 3 = Mitarbeiter. Siehe adr-0007-rollen-permissions-modell.
• Modul-Entitlements (seit Phasen 0–3, Sept. 2026): Jeder Mandant hat einen Satz aktiver Module (Fachmodule wie Rapport/Angebote, Kanäle wie WhatsApp, Integrationen wie Google Calendar). Das zentrale Manifest (packages/domain/src/modules/manifest.ts) beschreibt je Modul (ID, Label, Abhängigkeiten, Routes, Tools, Menü-Zeilen, Prompt-Regeln, Jobs, Tabellen). Guards (requireModule, ifModule) in der Domain + Middleware-Filter + Agent-Registry erzwingen, dass ein Bereich ohne entsprechende Berechtigung mit einheitlichen Fehlermeldungen endet. Siehe Plan und Agent-Tools Pflegeregel.
• Migrationen: idempotent (IF NOT EXISTS, DO $$ … EXCEPTION), per database/migrate.ts.
• Notizen: notes ist seit Migration 038 ein JSONB-Array auf mehreren Entitäten.

Verwandte Notes

• adr-0001-landing-app-domain-split · adr-0002-shared-domain-layer · adr-0003-whatsapp-agent-rebuild
• work7-agent-infra-rebuild · work7-agent-architecture