Olympus/ARCHITECTURE.md

Olympus CRM Architektur

Projektueberblick

Olympus CRM ist als mehrschichtige CRM-Anwendung aufgebaut. Die Architektur trennt klar zwischen Browser, Frontend/BFF, Backend-API und Datenbank.

Die zentrale Regel lautet:

Der Browser kommuniziert ausschliesslich mit Athena. Athena kommuniziert serverseitig mit Hermes. Hermes kommuniziert mit PostgreSQL.

Diese Trennung ist verbindlich, besonders fuer Authentifizierung, API-Zugriffe und spaetere Modul-Erweiterungen wie Kunden, Projekte, Lieferanten, Kontakte und Mitarbeiter.

Systemkomponenten

Athena: Next.js 16 Frontend

Athena liegt unter frontend/athena und ist das Frontend sowie die BFF-Schicht des Systems.

Aufgaben:

• rendert die Benutzeroberflaeche mit Next.js 16 App Router
• stellt eigene API-Routes unter /api/... bereit
• setzt und loescht das HttpOnly-Auth-Cookie
• ruft Hermes serverseitig auf
• schuetzt Seiten ueber proxy.ts

Der Browser darf keine Hermes-URLs direkt aufrufen.

Hermes: FastAPI Backend

Hermes liegt unter backend/hermes und stellt die interne Backend-API bereit.

Aufgaben:

• validiert Requests mit Pydantic v2
• verarbeitet Fachlogik und Persistenz
• prueft JWT Bearer Tokens
• stellt REST-Endpunkte bereit
• nutzt SQLAlchemy 2.x fuer Datenbankzugriffe
• setzt keine Browser-Cookies

Hermes bleibt Cookie-frei. Authentifizierte Hermes-Endpunkte erwarten Authorization: Bearer <jwt>.

PostgreSQL Datenbank

PostgreSQL ist die relationale Datenbank fuer Olympus CRM. Hermes greift ueber SQLAlchemy darauf zu.

Schemaaenderungen erfolgen ueber Alembic-Migrationen. Manuelle Datenbankeingriffe sind nur in Notfaellen zulaessig und muessen nachvollziehbar dokumentiert werden.

Docker Compose

Die gemeinsame Docker-Compose-Konfiguration liegt im Projektroot in docker-compose.yml.

Sie verbindet:

• hermes
• athena
• das konfigurierte Docker-Netzwerk
• die notwendigen Runtime-Umgebungsvariablen

Im gemeinsamen Compose-Stack wird Athena am Host veroeffentlicht. Hermes wird nur intern im Docker-Netzwerk exponiert und von Athena ueber HERMES_INTERNAL_URL erreicht.

BFF-Architektur

Olympus nutzt eine Backend-for-Frontend-Architektur.

Regeln:

• Browser spricht ausschliesslich mit Athena.
• Athena spricht serverseitig mit Hermes.
• Hermes setzt keine Browser-Cookies.
• Cross-Origin-Cookies werden nicht verwendet.
• Frontend-API-Zugriffe laufen ueber relative Athena-Routen wie /api/users.

Der Datenfluss bleibt dadurch kontrolliert, sicher und leichter hinter Reverse Proxies betreibbar.

Authentifizierungsfluss

Login

1. Der Browser sendet Benutzername und Passwort an Athena: POST /api/login.
2. Athena ruft serverseitig Hermes auf: POST /auth/login.
3. Hermes validiert die Zugangsdaten.
4. Hermes gibt JWT, Ablaufzeit und Benutzerdaten als JSON zurueck.
5. Athena setzt das JWT in einem HttpOnly-Cookie.
6. Der Browser wird auf eine geschuetzte Seite weitergeleitet.

Hermes setzt kein Cookie.

Logout

1. Der Browser sendet POST /api/logout an Athena.
2. Athena loescht das HttpOnly-Cookie.
3. Der Benutzer wird zur Login-Seite gefuehrt.

Aktueller Benutzer

Athena stellt GET /api/me bereit und ruft dafuer serverseitig Hermes GET /auth/me auf. Der Header laedt den aktuellen Benutzer ausschliesslich ueber diese BFF-Route und zeigt bevorzugt Vorname plus Nachname, danach den Benutzernamen und vor dem Laden Benutzer.

Der Browser erhaelt dabei kein Token und ruft Hermes nicht direkt auf.

HttpOnly Cookie

Das Auth-Cookie wird von Athena gesetzt.

Eigenschaften:

• HttpOnly
• SameSite=Lax
• Path=/
• Secure in Produktion
• Ablaufzeit orientiert sich an der JWT-Ablaufzeit

Tokens duerfen nicht in localStorage oder sessionStorage gespeichert werden.

JWT

Hermes erzeugt JWT Access Tokens.

Wichtige Claims:

• sub: Benutzername
• exp: Ablaufzeit
• iat: Ausstellungszeitpunkt
• iss: konfigurierter Issuer
• type: Token-Typ, aktuell access

Issuer

Der Issuer wird ueber JWT_ISSUER konfiguriert. Hermes prueft den Issuer bei der Token-Validierung.

Ablaufzeit

Die Ablaufzeit wird ueber ACCESS_TOKEN_EXPIRE_MINUTES konfiguriert. Athena nutzt die von Hermes gelieferte Ablaufzeit fuer das Cookie.

proxy.ts

Athena schuetzt Routen ueber frontend/athena/proxy.ts.

Aufgaben:

• geschuetzte Bereiche ohne Cookie auf /login umleiten
• eingeloggte Benutzer von /login auf /dashboard umleiten

API-Datenfluss

Standardfluss:

Browser -> Athena /api/... -> Hermes -> PostgreSQL

Beispiel Benutzerliste:

Browser
  GET /api/users

Athena
  GET {HERMES_INTERNAL_URL}/users
  Authorization: Bearer <jwt aus HttpOnly Cookie>

Hermes
  SQLAlchemy Query gegen PostgreSQL

Athena ist die einzige API-Oberflaeche fuer den Browser.

Dashboard

Das Dashboard liegt in Athena unter /dashboard und bezieht seine Daten ueber die BFF-Route GET /api/dashboard/summary.

Hermes stellt dafuer GET /dashboard/summary bereit. Der Endpunkt ist mit dashboard.read geschuetzt und liefert nur Datenbloecke, fuer die der aktuelle Benutzer weitere Berechtigungen besitzt.

Beispiele:

• Kundenstatistiken nur mit customers.read
• Benutzerstatistiken nur mit users.read
• Rollenstatus nur mit roles.read

Nicht vorhandene Module wie Aufgaben, Tickets oder Projekte werden nicht mit Fake-Daten gefuellt. Stattdessen liefert das Dashboard leere Widgets mit klarer Meldung.

Activity Feed

Der Activity Feed ist Teil der v0.5.0-Qualitaetsplattform.

Athena ruft GET /api/activity-feed auf. Die BFF-Route ruft serverseitig Hermes GET /activity-feed auf.

Der Feed basiert auf persistenten Audit Logs und zeigt die letzten relevanten Aktivitaeten. Hermes filtert die Eintraege anhand der Berechtigungen des aktuellen Benutzers. Ein Benutzer sieht dadurch nur Aktivitaeten zu Bereichen, fuer die er Leserechte besitzt.

RBAC: Rollen und Berechtigungen

Olympus verwendet ein serverseitiges RBAC-System als Grundlage fuer alle CRM-Module.

Konzepte:

• Benutzer besitzen genau eine primaere Rolle.
• Rollen besitzen mehrere Berechtigungen.
• Berechtigungen sind stabile String-Keys wie users.read.
• Hermes prueft Berechtigungen serverseitig ueber Dependencies.
• Athena darf Permissions fuer UI-Sichtbarkeit nutzen, aber niemals als Auth-Quelle.

Tabellen:

• roles
• permissions
• role_permissions
• users.role_id

Das alte users.role-Feld bleibt vorerst als Legacy-Kompatibilitaet erhalten. Neue Logik verwendet users.role_id und die roles-Beziehung.

Standardrollen

• administrator
• management
• sales
• technician
• support
• warehouse
• guest

administrator erhaelt alle Berechtigungen. management erhaelt mindestens Lesezugriff auf Dashboard, Benutzer, Kunden, Projekte und Tickets. guest erhaelt minimal dashboard.read.

Standardberechtigungen

Benutzer:

• users.read
• users.create
• users.update
• users.delete
• users.password.update

Rollen:

• roles.read
• roles.create
• roles.update
• roles.delete
• roles.assign

Kunden:

• customers.read
• customers.create
• customers.update

Initial Admin Bootstrap

Hermes prueft beim Startup nach dem RBAC-Seed, ob mindestens ein aktiver Benutzer existiert. Existiert ein aktiver Benutzer, wird kein Benutzer automatisch erstellt.

Existiert kein aktiver Benutzer, kann Hermes ueber optionale Umgebungsvariablen einen initialen Administrator anlegen:

• INITIAL_ADMIN_USERNAME
• INITIAL_ADMIN_EMAIL
• INITIAL_ADMIN_PASSWORD
• INITIAL_ADMIN_FIRST_NAME
• INITIAL_ADMIN_LAST_NAME

Benutzername, E-Mail und Passwort sind fuer die automatische Anlage erforderlich. Fehlen Werte oder ist die E-Mail ungueltig, startet Hermes weiter und schreibt nur eine Warnung ohne Secrets. Das Passwort wird mit der bestehenden hash_password-Funktion gehasht. Der Benutzer erhaelt role_id der Systemrolle administrator und das Legacy-Feld role=administrator.

Kundenimport

Hermes stellt fuer CSV-Importe zwei Endpunkte bereit:

• POST /customers/import/preview
• POST /customers/import/commit

Athena stellt die Browser-BFF-Routen bereit:

• POST /api/customers/import/preview
• POST /api/customers/import/commit
• GET /api/customers/import/template

Der Browser sendet Multipart-FormData nur an Athena. Athena leitet die Datei serverseitig mit Bearer Token aus dem HttpOnly-Cookie an Hermes weiter. Hermes begrenzt CSV-Dateien auf 5 MB, bevorzugt UTF-8, erkennt Semikolon und Komma und ignoriert leere Zeilen.

Importmodi:

• create_only: neue Kunden erstellen, bestehende Kundennummern ueberspringen
• update_existing: bestehende Kunden anhand der Kundennummer aktualisieren
• upsert: bestehende Kunden aktualisieren und neue Kunden erstellen

RBAC:

• Preview benoetigt customers.read
• Commit mit create_only benoetigt customers.create
• Commit mit update_existing benoetigt customers.update
• Commit mit upsert benoetigt customers.create und customers.update

CSV-Spalten:

customer_number;company_name;legal_name;customer_type;status;industry;website;email;phone;tax_number;vat_id;notes;address_type;street;postal_code;city;state;country;address_is_primary;contact_first_name;contact_last_name;contact_position;contact_email;contact_phone;contact_mobile;contact_is_primary;contact_notes

Pflichtfeld ist company_name. Wenn customer_number, customer_type oder status fehlen, erzeugt der Import fuer neue Kunden eine Kundennummer bzw. nutzt produktive Defaults und weist in der Preview darauf hin. Vollstaendige CSV-Inhalte werden nicht im Audit Log gespeichert.

• customers.delete

Projekte:

• projects.read
• projects.create
• projects.update
• projects.delete

Tickets:

• tickets.read
• tickets.create
• tickets.update
• tickets.delete

Dashboard und System:

• dashboard.read
• system.settings.read
• system.settings.update

Audit:

• audit_logs.read

Berechtigungspruefung

Zentrale Hermes-Dependencies:

• get_current_user
• get_current_active_user
• require_permission("permission.name")
• require_any_permission([...])
• require_all_permissions([...])

Backend-Endpunkte muessen immer selbst pruefen. Frontend-Helfer wie hasPermission dienen nur dazu, Buttons oder Navigation auszublenden.

Rollen-API

Hermes:

• GET /roles
• GET /roles/{id}
• POST /roles
• PUT /roles/{id}
• DELETE /roles/{id}
• PUT /roles/{id}/permissions
• GET /permissions

Athena stellt entsprechende BFF-Routen unter /api/roles, /api/permissions und /api/me bereit.

Benutzerverwaltung

Die Benutzerverwaltung ist das erste Enterprise-Modul und dient als Vorlage fuer weitere Module.

Funktionen:

• Benutzerliste
• Detailseite
• Erstellen
• Bearbeiten
• Loeschen
• Passwort separat aendern
• Suche, Filter, Sortierung und Pagination im Frontend

Backend-Endpunkte in Hermes:

• GET /users
• GET /users/{id}
• POST /users
• PUT /users/{id}
• PUT /users/{id}/password
• DELETE /users/{id}

Athena stellt die passenden BFF-Routen unter /api/users und /api/users/[id] bereit.

Diese Endpunkte sind per RBAC geschuetzt:

• GET /users und GET /users/{id}: users.read
• POST /users: users.create und fuer Rollenzuweisung roles.assign
• PUT /users/{id}: users.update; Rollenwechsel benoetigt roles.assign
• PUT /users/{id}/password: users.password.update
• DELETE /users/{id}: users.delete

Passwortaenderung

Wenn beim Bearbeiten kein Passwort uebergeben wird, bleibt das bestehende Passwort unveraendert.

Wenn ein Passwort gesetzt wird, wird es in Hermes mit pwdlib neu gehasht.

Self-Delete-Schutz

Der aktuell angemeldete Benutzer darf sich nicht selbst loeschen. Hermes verhindert dies serverseitig.

Rollenmodell

Benutzer besitzen eine primaere RBAC-Rolle ueber role_id. Die Rolle bestimmt die serverseitigen Berechtigungen.

Kundenmodul

Das Kundenmodul ist das zweite Enterprise-Modul und folgt den gleichen Grundsaetzen wie die Benutzerverwaltung:

• Hermes stellt REST-Endpunkte bereit.
• Athena proxyt diese Endpunkte ueber /api/customers.
• Der Browser spricht nicht direkt mit Hermes.
• Berechtigungen werden serverseitig in Hermes geprueft.
• Die UI nutzt Permissions nur fuer Sichtbarkeit und Bedienkomfort.

Hermes-Endpunkte:

• GET /customers
• GET /customers/{id}
• POST /customers
• PUT /customers/{id}
• DELETE /customers/{id}
• GET /customers/{id}/contacts
• POST /customers/{id}/contacts
• PUT /customers/{id}/contacts/{contact_id}
• DELETE /customers/{id}/contacts/{contact_id}

Athena-BFF-Routen:

• GET /api/customers
• POST /api/customers
• GET /api/customers/[id]
• PUT /api/customers/[id]
• DELETE /api/customers/[id]
• GET /api/customers/[id]/contacts
• POST /api/customers/[id]/contacts
• PUT /api/customers/[id]/contacts/[contactId]
• DELETE /api/customers/[id]/contacts/[contactId]

Tabellen:

• customers
• customer_addresses
• customer_contacts

Kunden-Permissions:

• customers.read
• customers.create
• customers.update
• customers.delete

Kontakte und Adressen gehoeren fachlich zum Kunden und werden aktuell ueber customers.read beziehungsweise customers.update gesteuert.

Ein Kunden-Delete entfernt aktuell den Kunden inklusive Adressen und Ansprechpartnern. Fuer spaetere Projekte oder Tickets ist ein fachlicher Loeschschutz vorzubereiten, sobald diese Module existieren.

Audit Logs

Audit Logs sind die zentrale Nachvollziehbarkeitsschicht fuer v0.5.0.

Hermes persistiert relevante Ereignisse in der Tabelle audit_logs.

Erfasste Informationen:

• handelnder Benutzer
• Aktion, z. B. users.update oder customers.delete
• Objekttyp und Objekt-ID
• lesbares Objektlabel
• IP-Adresse und User-Agent
• Vorher-/Nachher-Daten fuer Aenderungen
• Metadaten fuer Kontextinformationen
• Erstellungszeitpunkt

Sensible Felder wie Passwoerter, Tokens und Secrets werden vor dem Schreiben maskiert.

Audit Logs werden aktuell fuer diese Bereiche geschrieben:

• Login erfolgreich/fehlgeschlagen
• Benutzer erstellen, bearbeiten, loeschen, Passwort aendern
• Rollen erstellen, bearbeiten, loeschen, Berechtigungen aendern
• Kunden erstellen, bearbeiten, loeschen
• Ansprechpartner erstellen, bearbeiten, loeschen

Hermes-Endpunkte:

• GET /audit-logs
• GET /activity-feed

Athena-BFF-Routen:

• GET /api/audit-logs
• GET /api/activity-feed

Die Audit-Log-UI liegt unter frontend/athena/app/audit-logs und ist ueber audit_logs.read sichtbar.

API-Response-Standard

Neue Plattform-Endpunkte verwenden eine einheitliche Response-Huelle:

{
  "success": true,
  "data": {},
  "message": "Daten geladen"
}

Fehlerantworten aus Hermes verwenden ein konsistentes Format mit success, message, error_code und details. Fuer bestehende Athena-Fehlerbehandlung bleibt detail zusaetzlich erhalten.

Logging

Hermes konfiguriert Logging zentral ueber backend/hermes/app/core/logging.py.

HTTP-Requests werden strukturiert mit Methode, Pfad, Statuscode und Dauer geloggt. Fachliche Ereignisse bleiben in den API-Modulen als strukturierte Logeintraege erhalten.

Das Runtime-Loglevel wird ueber LOG_LEVEL gesteuert.

Frontend-Feedback

Athena nutzt einen globalen Toast-Provider fuer konsistente Erfolgs- und Fehlermeldungen.

Aktuell werden Toasts in den CRUD-Flows fuer Benutzer, Rollen, Kunden und Ansprechpartner genutzt. Inline-Fehler bleiben dort erhalten, wo sie fuer Formulare und Dialoge hilfreich sind.

Wissensdatenbank / Service Library

v0.6.0 fuehrt das Modul Wissensdatenbank ein. Es verwaltet Hersteller, Geraete und Modelle, Dokumente sowie Reparaturhinweise fuer Funktechnik, Elektronikreparatur und Werkstattbetrieb.

Hermes stellt dafuer Tabellen mit dem Prefix knowledge_ bereit:

• knowledge_manufacturers
• knowledge_devices
• knowledge_documents
• knowledge_notes
• knowledge_categories

Athena stellt die BFF-Routen unter /api/knowledge/... bereit. Der Browser spricht weiterhin ausschliesslich mit Athena.

Knowledge-Dateispeicherung

Dokumentuploads werden in v0.6.0 lokal im Hermes-Container oder in einem gemounteten Volume gespeichert.

Konfiguration:

• KNOWLEDGE_STORAGE_PATH, Default /data/knowledge
• KNOWLEDGE_MAX_UPLOAD_MB, Default 50

Docker Compose bindet das persistente Volume knowledge-data nach /data/knowledge ein. Dieses Volume darf nicht geloescht werden, wenn lokale Knowledge-Dateien erhalten bleiben sollen.

Erlaubte Uploadtypen:

• PDF
• JPG/JPEG
• PNG
• WEBP
• TXT
• ZIP

Hermes normalisiert Dateinamen, validiert Extension und MIME-Type, begrenzt die Uploadgroesse und erzwingt, dass gespeicherte und heruntergeladene Dateien innerhalb von KNOWLEDGE_STORAGE_PATH liegen.

Knowledge-RBAC

Neue Berechtigungen:

• knowledge.read
• knowledge.create
• knowledge.update
• knowledge.delete
• knowledge.upload
• knowledge.download

Standardrollen:

• administrator: alle Knowledge-Rechte
• management: knowledge.read, knowledge.download
• technician: knowledge.read, knowledge.create, knowledge.update, knowledge.upload, knowledge.download
• support: knowledge.read, knowledge.download
• guest: keine Knowledge-Rechte

Hermes erzwingt diese Rechte serverseitig. Athena nutzt sie nur fuer Navigation und UI.

Paperless-Vorbereitung

Eine echte Paperless-ngx-Integration ist in v0.6.0 nicht aktiv. Dokumente enthalten bereits paperless_document_id und external_url, damit spaeter ein PaperlessConnector angebunden werden kann. API-Keys oder verpflichtende Paperless-Umgebungsvariablen werden in v0.6.0 nicht eingefuehrt.

Spaetere Verknuepfungen sind fuer Kunden, Projekte, Tickets und Reparaturen vorgesehen.

Verzeichnisstruktur

backend/hermes
  app/
    api/
    audit/
    core/
    db/
    models/
    repositories/
    schemas/
  alembic/
  alembic.ini
  dockerfile
  pyproject.toml

frontend/athena
  app/
    api/
    audit-logs/
    customers/
    roles/
    users/
  components/
  lib/
  types/
  proxy.ts
  Dockerfile
  package.json

docker-compose.yml

Umgebungsvariablen

Hermes

DATABASE_URL

PostgreSQL-Verbindungsstring.

SECRET_KEY

Signierschluessel fuer JWTs. Muss geheim bleiben.

JWT_ISSUER

Erwarteter JWT-Issuer, z. B. hermes.

ACCESS_TOKEN_EXPIRE_MINUTES

Ablaufzeit fuer Access Tokens in Minuten.

LOG_LEVEL

Runtime-Loglevel fuer Hermes, z. B. INFO, WARNING oder ERROR.

KNOWLEDGE_STORAGE_PATH

Lokales Speicherverzeichnis fuer Knowledge-Dateien. Default /data/knowledge.

KNOWLEDGE_MAX_UPLOAD_MB

Maximale Uploadgroesse fuer Knowledge-Dokumente in MB. Default 50.

Athena

HERMES_INTERNAL_URL

Serverseitige URL, ueber die Athena Hermes erreicht.

AUTH_COOKIE_SECURE

Steuert das Secure-Flag des Cookies. In Produktion true.

Datenbankmigrationen

Olympus verwendet Alembic fuer Datenbankmigrationen.

Regeln:

• Schemaaenderungen immer ueber Alembic.
• Migrationen muessen ins Repository aufgenommen werden.
• Vor Deployment alembic upgrade head testen.
• Keine manuellen DB-Aenderungen ausser in Notfaellen.

Typischer Ablauf:

cd backend/hermes
alembic upgrade head

Sicherheitsprinzipien

Verbindliche Regeln:

• Keine Tokens im localStorage.
• Keine Tokens im sessionStorage.
• Keine Browserzugriffe auf Hermes.
• Keine Cross-Origin-Cookies.
• Hermes bleibt Cookie-frei.
• Athena setzt HttpOnly Cookies.
• Mutierende Athena-API-Routes pruefen Same-Origin.
• Hermes prueft JWTs serverseitig.
• Hermes prueft RBAC-Berechtigungen serverseitig.
• Secrets gehoeren in Umgebungsvariablen, nicht in den Code.

Produktionshinweise

Fuer Produktion gilt:

• HTTPS ist erforderlich.
• AUTH_COOKIE_SECURE=true setzen.
• Reverse Proxy ist moeglich und soll Forwarded Header korrekt setzen.
• HERMES_INTERNAL_URL muss serverseitig erreichbar sein.
• SECRET_KEY muss stark, geheim und stabil sein.
• Datenbankmigrationen vor App-Rollout ausfuehren.

Lokaler HTTP-Betrieb ist nur fuer Entwicklung gedacht. In Produktion duerfen keine unsicheren Cookie-Einstellungen verwendet werden.