nexarch/PRODUKTARCHITEKTUR.md

NEXARCH 2.0 – Produktarchitektur

Stand: 2026-08-26. Zusammenführung aller bisherigen Entscheidungen aus nexarch-state.json und den sieben Boards zu einem lesbaren Gesamtbild. Kein neues Konzept — reine Synthese des bereits Entschiedenen.

1. Produktvision

NEXARCH ist die Nachfolgeplattform von archivmail (E-Mail-Archivierung) und archivdms (Dokumentenmanagement) — nicht als Umbenennung, sondern als modulare Neuentwicklung unter der Positionierung "Next Generation Information Management": E-Mails, Dokumente, digitale Archivierung, OCR, Volltextsuche, Workflows, Compliance, Integrationen, KI — als ein zusammenhängendes System, nicht als zwei getrennte Werkzeuge nebeneinander.

1a. Vorbildsysteme

NEXARCH vereint die Stärken bestehender Systeme und vermeidet deren bekannte Schwächen (Details: dms-kanban/known-issues-archivdms.md, dms-kanban/known-issues-archivmail.md).

Bereich	Vorbildsysteme
Mail	archivmail (eigenes Produkt, Vorgänger), MailPiler
DMS	paperless-ngx, Alfresco, Docspell, ecoDMS, archivdms (eigenes Produkt, Vorgänger)

Weitere Vergleichsprojekte (z. B. OpenKM, Nuxeo, Mayan EDMS, Seafile) sind noch zu prüfen. Für das DMS-Modul siehe auch dms/README.md.

2. Architekturprinzip

Ein modularer Monolith aus sieben eigenständigen, aber koordinierten Diensten — kein Microservice-Zwang, aber klare Dienstgrenzen mit eigenem Datenmodell, eigenem Go-Binary, eigenem Kanban-Board:

                          ┌─────────────┐
                          │    Core     │   Identity · Tenancy · Auth · Rollen
                          │  (53 T/142) │   Lizenzierung · Audit · Config
                          └──────┬──────┘   API-Grundgerüst · Monitoring
                                 │  (JWKS, Service-Credentials, Rückkanal-APIs)
        ┌───────────┬───────────┼───────────┬───────────┬───────────┐
        ▼           ▼           ▼           ▼           ▼           ▼
     ┌─────┐     ┌─────┐    ┌────────┐  ┌──────────┐ ┌─────┐    ┌─────────┐
     │ DMS │     │Mail │    │Archive │  │ Workflow │ │ AI  │    │ Connect │
     │64/195│    │59/151│   │27/73   │  │28/76     │ │40/113│   │27/75    │
     └─────┘     └─────┘    └────────┘  └──────────┘ └─────┘    └─────────┘
   Dokumente    E-Mail    Retention/   Genehmigung/  KI-Klassi-  ERP/DATEV/
   Ordner/Akte  IMAP/SMTP WORM/Backup  Akte/Vermerk/ fizierung/  M365/Fremd-
   Metadaten    Postfach  eDiscovery   Wiedervorlage Extraktion/ DMS/Backup-
   Versionen    Import    Kennzahlen   Routing       Chat        Ziele

(T = Tickets, letzte Zahl = Personentage — Stand siehe nexarch-state.json → boards.)

Jedes Fachmodul (DMS/Mail/Archive/Workflow/AI/Connect) hat sein eigenes Datenmodell für seinen Fachgegenstand, implementiert aber keine eigene Identität/Rechte/Mandantenlogik — das ist die zentrale Architekturentscheidung, aus drei Konsolidierungsrunden hervorgegangen (Abschnitt 4).

3. Warum sieben Boards und nicht mehr oder weniger

Die Aufteilung ist nicht die ursprünglich im Master-Prompt skizzierte (die u.a. Search und OCR als eigene Module vorsah) — sie hat sich beim Durcharbeiten verschoben:

• Search/OCR bleiben je Fachmodul (DMS und Mail haben je eigene SRC-Epics) — bewusste Entscheidung, weil E-Mail- und Dokument-Suche als hinreichend unterschiedlich bewertet wurden, um eine gemeinsame Suchschicht nicht zu rechtfertigen.
• Archive, Workflow, AI und Connect sind dagegen als eigene Boards entstanden, weil beim Bauen von DMS/Mail wiederholt auffiel, dass dieselbe Fachlogik (Retention/WORM, Genehmigungsprozesse, KI-Klassifizierung, API-Infrastruktur) unabhängig in mehreren Boards geplant wurde — siehe Abschnitt 4.

4. Konsolidierungsverlauf — was zentral wurde und warum

Vier Konsolidierungsrunden, jede aus demselben wiederkehrenden Muster: zwei oder mehr Boards planten dieselbe Fachlogik unabhängig voneinander.

Fachlogik	War dupliziert in	Jetzt zentral in	Ergebnis
Benutzer, Rollen, SSO, LDAP, Mandanten	DMS (FDN-05, IAM-01..07)	Core	DMS 87→79 Tickets
Retention, WORM, Compliance, Backup, Kennzahlen	DMS (REP-01..06), Mail (REP-01..09)	Archive	DMS 79→73, Mail 70→61
Workflow-Engine, Genehmigungen, Aufgaben, Routing	DMS (WFL-01..07)	Workflow	DMS 73→66
KI-Klassifizierung/Extraktion/Zusammenfassung	DMS (MET-06)	AI	DMS 66→65
REST-API-Grundgerüst, Token, Rate-Limiting, Webhooks	DMS (INT-01/02/05), Mail (INT-01/02/03/04)	Core	DMS 66→64, Mail 62→59
Krypto-Master-Key-Verwaltung	DMS (FDN-09), Mail (ARC-02) — je eigene Schlüsselverwaltung	Core (nur Master-Key, Objekt-Verschlüsselung bleibt modul-lokal)	kein Ticketverlust, aber Duplikat im sicherheitskritischsten Bereich beseitigt

Die Konsequenz für das Architekturbild: Core ist nicht "noch ein Modul", sondern das Fundament, auf dem alle anderen sechs aufbauen — sichtbar auch daran, dass Connect (das jüngste, am weitesten außen liegende Board) am stärksten von einem vollständigen Core abhängt (sieben verschiedene Core-API-Tickets, siehe ROADMAP.md Abschnitt 1).

5. Modulübergreifende Referenz-Architektur

Kein Modul kopiert die Daten eines anderen — stattdessen ein wiederkehrendes Adapter-Muster, in drei Varianten je nach Zweck:

1. Push-Registrierung (Archive RET-05, Workflow ENG-02, AI GOV-01): DMS/Mail melden ein Objekt (Dokument-ID, Mail-ID) bei einem Querschnitts-Board an, ohne dessen Rohdaten zu duplizieren — Archive weiß dann "dieses Objekt hat eine Aufbewahrungsfrist", Workflow weiß "dieses Objekt gehört zu einer Akte", ohne den Dokumentinhalt selbst zu besitzen.
2. Pull-Rückkanal (Workflow VOR-04): die Gegenrichtung — DMS/Mail fragen bei Workflow ab, was zu einem Objekt bekannt ist (Vermerke, Wiedervorlage), damit diese Information im Ursprungsmodul sichtbar wird, statt nur in einer separaten Workflow-Oberfläche zu verschwinden. Ohne diesen Rückkanal wäre die Push-Registrierung für Anwender faktisch unsichtbar — dieser Zusammenhang wurde erst nachträglich im Gespräch aufgedeckt, nicht von Anfang an mitgeplant.
3. Externe Konnektoren (Connect ENG-01..DMS2-03): dieselbe Idee nach außen gewendet — Fremdsysteme (ERP, DATEV, M365, andere DMS) werden über Connector-Adapter angebunden, nicht durch Direktintegration in jedem Fachmodul einzeln.

Gemeinsamer Nenner aller drei: Referenz statt Kopie, Adapter statt Direktkopplung.

Go-internal/-Pakete sind zwischen den Modulen nicht sichtbar; identische Querschnittspakete liegen deshalb im versionierten Modul common/ (Git-Tags common/vX.Y.Z, siehe common/README.md). So bleiben Module einzeln baubar (Docker, eigenes Repo, Partner-Build). Fachlich verschiedene Pakete (audittrail, cutoverstage, crypto) bleiben modul-lokal.

Dasselbe Prinzip gilt auch innerhalb eines Moduls, auf Code-Ebene: Hauptdateien/Entry-Points bleiben klein, Fachlogik wandert in eigene Module. Vor einer neuen Funktions-/Modul-Datei wird geprüft, ob dieselbe Funktionalität nicht schon woanders existiert (auch modulübergreifend, z. B. in Core) — keine doppelten Funktionsdateien. Das eigene Kanban-Planungswerkzeug wurde nach genau diesem Muster korrigiert (sieben kanban.html enthielten identisches JS/CSS als Volltext-Duplikat, damals in _shared/kanban.js/kanban.css ausgelagert) — die Boards selbst sind inzwischen komplett aus dem Repo entfernt (Ticket-Historie liegt in der Gitea-PR-Historie), das Prinzip "keine doppelten Funktionsdateien" gilt unverändert für den eigentlichen NEXARCH-Code.

6. Technische Architektur (Kurzfassung, Details in eigenen Dokumenten)

Ebene	Entscheidung	Vertiefung
Backend	Go (net/http, pgx/v5), ein Binary pro Modul	PROXMOX-DEPLOYMENT.md
Datenbank	PostgreSQL, Modell C (eine physisch getrennte Datenbank je Mandant plus Registry, RLS redundant)	SKALIERUNGSKONZEPT.md Abschnitt 4
Suche	Manticore (BM25), je Modul eigener Index	SKALIERUNGSKONZEPT.md Abschnitt 5
Warteschlange	Postgres-Jobqueue, kein Redis	SKALIERUNGSKONZEPT.md Abschnitt 7
Storage	S3-kompatible Abstraktion, einheitliche Pfadkonvention	STORAGE-KONZEPT.md
Frontend	Next.js/React/TypeScript	—
Auth	JWT + lokale JWKS-Verifikation (kein synchroner Core-Zwang pro Request)	SICHERHEITSKONZEPT.md Abschnitt 1, Core API-05
Deployment	natives systemd, Docker optional für SaaS	PROXMOX-DEPLOYMENT.md
Hochverfügbarkeit	Core-Anwendungsschicht zustandslos, Postgres-Primary/Replica-Failover ab Stufe 2	SKALIERUNGSKONZEPT.md Abschnitt 10

7. Betriebsmodelle

Drei Stufen, ein Techstack (kein Sonderpfad für SaaS vs. On-Premise, außer Docker als SaaS-Zusatzoption):

• Stufe 1 — Einzel-Proxmox-LXC, für kleine/mittlere Kunden, On-Premise-Standardfall.
• Stufe 2 — verteilte Installation, mehrere App-Instanzen + Primary/Replica-DB, für größere Kunden oder den SaaS-Betrieb des Anbieters selbst.
• Stufe 3 — dedizierte Instanz pro Großkunde (Private Cloud), strukturell Stufe 1 oder 2, nur organisatorisch als eigene Umgebung abgegrenzt.

Was noch fehlt: eine konkrete Preis-/Lizenzstruktur (Benutzer/Monat vs. Modul/Monat vs. Enterprise) — die TECHNISCHE Seite der Lizenzierung (Core LIC-Epic: Feature-Flags, Modulaktivierung pro Tenant, Nutzungszähler inkl. Speicherverbrauch) ist fertig geplant, die GESCHÄFTLICHE Seite (was kostet was) ist eine offene Entscheidung, siehe nexarch-state.json → fehlende_konzeptdokumente.

8. Migration von den Altsystemen

Eigenes Dokument (MIGRATIONSKONZEPT.md), hier nur die Kernaussage: Big-Bang-Stichtag mit vorgeschalteter Generalprobe, größtes Einzelrisiko ist die Zusammenführung von Tenants/Benutzern, die in archivmail und archivdms unabhängig, aber teilweise für dieselben Kunden entstanden sind — mit Pflicht-Freigabe durch einen Menschen, kein automatischer Merge.

9. Dokumentenlandkarte

Dokument	Inhalt
nexarch-state.json	maschinenlesbarer Gesamtzustand, Entscheidungsverlauf, Board-Zahlen
PRODUKTARCHITEKTUR.md	dieses Dokument — lesbare Gesamtübersicht
MIGRATIONSKONZEPT.md	Datenübernahme aus archivmail/archivdms
SKALIERUNGSKONZEPT.md	Wachstumspfad, Betriebsstufen, Core-Hochverfügbarkeit
STORAGE-KONZEPT.md	Objekt-Storage, Pfadkonvention, Lebenszyklus
SICHERHEITSKONZEPT.md	Auth/Autorisierung/Verschlüsselung/Incident-Response
PROXMOX-DEPLOYMENT.md	konkretes LXC-Layout je Betriebsstufe
ROADMAP.md	Board-Reihenfolge, kritische Pfade, Phasenplan
MEMORY.md / nexarch-state.json (Claude-Session-Speicher)	Einstiegspunkt für künftige Arbeitssitzungen

Noch offen: SaaS-/Multi-Tenant-Betriebsmodell als eigenes ausformuliertes Dokument (Abschnitt 7 hier deckt die technische Seite ab, nicht die vertraglich-organisatorische), UI/UX-Konzept, Lizenzmodell konkret (Preisgestaltung).