kundencenter/docs/architektur.md
Claude (KI) a0dd7c3940 Architektur-Doku, ADR Job-Queue und automatische Modulgrenzen-Prüfung (#7)
- 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>
2026-10-06 12:05:59 +02:00

6.2 KiB
Raw Permalink Blame History

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
mail 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üfung canInOrg); Module registrieren ihre Rechte. Ticket-Rechte zusätzlich in platform/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.ts re-exportiert @kc/platform/config.