- docs/architektur.md: Prozesse, Pakete und erlaubte Abhängigkeiten, API-Module, Mail-Plattform/IMAP, Jobs, Querschnitt, offene Punkte. - docs/adr/0003-job-queue-in-mariadb.md. - ops/test/check-boundaries.mjs (ohne neue Abhängigkeit): prüft alle Importe gegen die Schichtregeln, inkl. Selbsttest; läuft in ci.sh. Gegenprobe: verbotener Modul-Querimport lässt den Lauf scheitern. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.2 KiB
Architektur
Stand: 06.10.2026 (Code-Stand nach den Plane-Tickets #95–#119). Entscheidungen im Detail: docs/adr/.
Überblick
Modularer Monolith in einem pnpm-Monorepo mit drei Prozessen und einer Datenbank:
| Prozess | Paket | Aufgabe | systemd |
|---|---|---|---|
| API | apps/api (Fastify) |
HTTP-API unter /v1, Rechte, Validierung, Audit, Jobs einplanen, Worker-Watchdog |
kc-api (:4100, nur 127.0.0.1) |
| Worker | apps/worker |
Job-Queue abarbeiten, Connector-Abgleich, Vertragslauf, Abrechnungslauf, IMAP-Abruf, Discord-Bot, Lizenzprüfung, Betriebsalarme | kc-worker |
| Web | apps/web (Next.js) |
Oberfläche; spricht ausschließlich über den Proxy /api/* → API |
kc-web (:4101, nur 127.0.0.1) |
Datenbank: MariaDB (utf8mb4_unicode_ci), Schema über nummerierte Migrationen in migrations/ (pnpm migrate, Sperre + Wiederanlauf siehe docs/betrieb-backup-restore.md). Kein Redis, keine Message-Queue – die Job-Queue liegt in MariaDB (ADR 0003).
Pakete und erlaubte Abhängigkeiten
apps/web ──HTTP──▶ apps/api ─┐
├─▶ packages/connectors ─▶ packages/connector-{keyhelp,plesk,licensing,mock} ─▶ packages/connector-sdk
apps/worker ─────┤ │
└─▶ packages/platform ◀──┘
| Paket | Darf importieren | Inhalt |
|---|---|---|
packages/connector-sdk |
nichts Internes | Connector-Vertrag (Connector, Capabilities, NormalizedResource, Fehlerklassen, httpJson) |
packages/connector-* |
nur @kc/connector-sdk |
Anbieter-Anbindungen; kennen weder Datenbank noch Apps |
packages/platform |
keine @kc-Pakete |
gemeinsame Schicht für API und Worker: DB, Konfiguration, Krypto, Audit-Kette, Jobs, Mail, Lizenz/Edition, Preise, Statusautomaten, Abrechnungslauf, Betriebsalarme, Ticket-Policy, CSV, Nummernkreise |
packages/connectors |
platform, connector-sdk, connector-* |
Registry der Connectoren, Abgleich, Provisionierung, Lifecycle-Aktionen, Vertragslauf |
apps/api |
platform, connectors, connector-sdk |
Module (s. u.), core/ (Auth, Policy, Fehler, Re-Exporte der Plattform), ops/ (Backup, Watchdog) |
apps/worker |
platform, connectors, connector-sdk |
Job-Handler, Discord, IMAP; kein Import von API-Code |
apps/web |
keine @kc-Pakete, nichts außerhalb apps/web |
UI; Rechte kommen aus /auth/me, durchgesetzt wird nur in der API |
Innerhalb der API importieren Module einander nicht; sie kommunizieren über core/, packages/platform und Jobs.
Automatische Prüfung: node ops/test/check-boundaries.mjs (läuft in ops/test/ci.sh und damit in der CI; --selftest prüft die Regeln selbst). Ein verbotener Import – z. B. apps/api/src/modules/tickets/* → ../invoices/index.js oder packages/connector-plesk → @kc/platform – lässt den Lauf scheitern. Tests (test/, *.test.ts) sind ausgenommen (API-Tests treiben den Worker-Job-Runner direkt an).
API-Module
Jedes Modul ist ein KcModule (apps/api/src/core/module.ts): Name, zusätzliche Rechte je Personal-/Organisationsrolle, register(app) mit den Routen. Eingetragen in apps/api/src/modules/index.ts.
| Modul | Zuständigkeit |
|---|---|
| system | /health, /ready, Betriebsübersicht (/admin/system: Jobs, Backup, Worker-Herzschlag, Betriebsalarme) |
| identity | Login, 2FA (TOTP, Wiederherstellungscodes), Sitzungen, Einladungen, Passwort-Reset, Personalverwaltung, Impersonation |
| customers | Kunden/Organisationen, Rechnungsprofil, Mitglieder, Übernahme aus Anbietern, Kundengrenze |
| audit | Audit-Protokoll (Hash-Kette), Export |
| connectors | Verbindungen (verschlüsselte Zugangsdaten), Capabilities, Abgleich |
| resources | Hosting-Konten/Lizenzen/Unterobjekte, Aktionen, Panel-Login, Auftragsliste |
| catalog | Produkte, Versionen, Laufzeitpreise |
| domains | Domain-Aufstellung, EK/VK, CSV, Verfügbarkeit |
| orders | Bestellungen, Freigabe, Verträge, Kündigung |
| tickets | Tickets, Nachrichten, Anhänge, Posteingang (IMAP-Mails, Zuordnung) |
| invoices | Rechnungen (Entwurf/Ausstellen/Storno), PDF, DATEV/CSV, Firmenstammdaten, Mahnüberblick, Abrechnungslauf |
| backup | Backup-Ziele, Passwort, Status |
| SMTP, Vorlagen, Protokoll, IMAP-Einstellungen | |
| discord | Bot-Einstellungen, OAuth-Verknüpfung |
| license | eigene Lizenz der Installation (Edition, Testmodus) |
| licensing | Lizenzverwaltung für weiterverkaufte Lizenzen (Licensing-Connector) |
Mail-Plattform (#106/#107)
Versand: packages/platform/src/mail.ts (SMTP-Konfiguration aus mail-Modul, DB-Vorlagen, Absender je Bereich, Protokoll). Ticket-Mails tragen eine signierte Message-ID (platform/ticketmail.ts). Empfang: der Worker ruft IMAP ab (apps/worker/src/mailbox.ts) und schreibt in inbox_messages/Tickets; die Bedienung (Zuordnen/Anhängen/Ignorieren) liegt im Tickets-Modul. Zuordnung nur mit signiertem Antwort-Bezug, sonst Posteingang.
Kommunikation über Jobs
API und Worker teilen sich keine Prozessdaten. Alles Asynchrone läuft über die Tabelle jobs (platform/jobs.ts: enqueue, in derselben Transaktion wie die fachliche Änderung möglich, Idempotenzschlüssel). Beispiele: discord.notify, mail.template, Connector-Aktionen, discord.ticket_sync. Details ADR 0003.
Querschnitt
- Rechte:
core/policy.ts(RBAC + ObjektprüfungcanInOrg); Module registrieren ihre Rechte. Ticket-Rechte zusätzlich inplatform/ticketPolicy.ts, damit der Worker (Discord) dieselben Regeln nutzt. Rollenmatrix:docs/sicherheit-und-bedrohungsmodell.md. - Audit: unveränderliche Hash-Kette (
platform/audit.ts, Trigger verhindern UPDATE/DELETE). - Geheimnisse: AES-GCM mit
KC_SECRET_KEY(platform/crypto.ts); Konfiguration in/etc/kundencenter/*.env, nie im Repo. - Edition/Lizenz:
platform/license.ts(signierte Antworten, Grenzen transaktional). - Zeit: alles in UTC (DB-Sitzung
time_zone = '+00:00').
Bekannte Abweichungen / offene Punkte
- Die Modulmatrix der eigenen Lizenz (billing/domains/provisioning/automation) ist noch nicht entschieden (#113); bis dahin gelten discord/imap/datev/backup_remote.
- Der frühere doppelte Config-Lader (ADR 0002) ist aufgelöst:
apps/api/src/core/config.tsre-exportiert@kc/platform/config.