MABEA/ergebnisse/19_technische_architektur.md

Prompt 19 – Technische Architektur

Bezug: alle fachlichen Ergebnisse 01-18. Erste Technikentscheidung, Basis für Prompt 20-22.

0. Techstack-Entscheidung (Nutzer)

• Backend: Python, FastAPI
• Datenbank: PostgreSQL
• Frontend: Responsive Web-App/PWA zuerst, native App (iOS/Android) als mögliche spätere Ergänzung
• Hosting: normaler Linux-Server/VPS, noch kein konkreter Anbieter — Architektur muss anbieterunabhängig/portabel sein; Docker dabei optional, keine Pflicht (siehe 9.)
• Deployment-Regel (Merkregel): ab hier nur Code/Konfigurationsdateien erzeugen, keine lokale Installation/Ausführung, Ziel ist externer Host.

1. Frontend

• Responsive PWA (Progressive Web App): eine Codebasis für PC, Tablet, Smartphone.
• PWA-Eigenschaften nutzen: Installierbarkeit auf Homescreen, Kamera-Zugriff für QR-/Barcode-Scan (Karte 10) via Browser-API (getUserMedia), Service Worker für Kurzzeit-Netzausfall-Pufferung (Prompt 17).
• Framework-Wahl offen für Umsetzungsphase (z. B. React/Vue), hier nur Architekturebene: Single-Page-App, spricht ausschließlich mit Backend über die API (Prompt 21).
• Native App (Roadmap) würde später dieselbe API nutzen, keine Backend-Änderung nötig — Grund, warum API-first-Ansatz (siehe 3.) architektonisch wichtig ist.

2. Backend

• Python, FastAPI (asynchron, automatische OpenAPI-Doku passt zu Prompt 21).
• Schichtenmodell: API-Layer (FastAPI Routen) → Service-/Domänenlogik-Layer (Statusmaschinen Kontrolle/Fehlbestand/Mindermenge, Prompt 02-04) → Datenzugriffs-Layer (ORM, z. B. SQLAlchemy) → PostgreSQL.
• Domänenlogik zentral gekapselt (z. B. eigenes Modul „Fehlbestand-Statusmaschine"), damit die zentrale Leitplanke „Mindermenge ≠ erledigt" (reihenfolge.md) an genau einer Stelle im Code durchgesetzt wird, nicht verstreut in mehreren Endpunkten.
• Authentifizierung (Karte 09): eigenes Auth-Modul, Passwort-Hashing (z. B. bcrypt/argon2), Session/Token-basiert (JWT oder Server-Session, Detail Prompt 21).

3. API-first-Prinzip

• Backend bietet ausschließlich eine dokumentierte REST-API (Prompt 21), kein serverseitiges HTML-Rendering.
• Vorteil: Web-PWA und später native App sind austauschbare Clients derselben API, kein Doppelaufwand bei Geschäftslogik.

4. Datenbank

• PostgreSQL, passend zum stark strukturierten, relationalen Datenmodell (Prompt 06): klare Entitäten, Fremdschlüssel, Historie/Audit-Anforderungen (Prompt 13) profitieren von ACID-Transaktionen.
• Migrationswerkzeug vorgesehen (z. B. Alembic) für versionierte Schemaänderungen, wichtig bei Vorlagen-Versionierung (Prompt 08) und künftigen Erweiterungen (Medikamente, Lager, Prüfungen).

5. Rollen/Rechte technisch

• Rollenmodell (Prompt 05) als Middleware/Dependency in FastAPI: jede Route deklariert benötigte Rolle(n)/Rechte, zentrale Prüfung statt verstreuter if-Abfragen.
• Zuständigkeits-Zuordnung (Karte 04) als Datenbank-gestützte Prüfung (n:m Benutzer↔Standort/Objekt), nicht hart codiert.

6. Historie/Auditierung technisch

• Eigene Tabelle(n) für Historieneinträge (Prompt 13), Append-only durch Anwendungslogik erzwungen (kein UPDATE/DELETE-Recht auf Historie-Tabellen für die Anwendung, nur INSERT).
• Serverseitige Zeitstempel (now() in der Datenbank oder Server-Uhrzeit im Backend, nie Client-Wert).

7. Benachrichtigungen

• E-Mail bei neuem Fehlbestand (Karte 05): asynchroner Versand (z. B. Hintergrundtask in FastAPI oder einfache Queue), damit Kontroll-Workflow nicht durch E-Mail-Versand blockiert wird.
• Kein Push in V1 (Karte 05) – kein zusätzlicher Dienst (Push-Server) nötig.

8. Offline-Unterstützung (Prompt 17)

• Kurzzeit-Pufferung im Frontend (Service Worker/lokaler Speicher im Browser), Übertragung an Backend bei wiederhergestellter Verbindung – rein clientseitiges Konzept, keine Backend-Sonderlogik nötig außer normalen, idempotenten API-Aufrufen.

9. Deployment-Architektur (anbieterunabhängig)

• Docker ist keine Priorität (Nutzerentscheidung) – Deployment stattdessen direkt auf dem Linux-Server/VPS: Backend als Python-Prozess (z. B. Uvicorn hinter systemd-Service), PostgreSQL als regulär installierter Dienst auf demselben oder separatem Server, Reverse-Proxy (z. B. nginx) für HTTPS/Routing.
• Statische PWA-Dateien vom Reverse-Proxy oder vom Backend selbst ausgeliefert – Detailentscheidung bei Umsetzung.
• Docker bleibt als spätere Option offen (z. B. falls Hosting-Umgebung es verlangt), ist aber kein Architekturzwang mehr.
• Wichtig (Merkregel): in dieser Konversation werden nur Code-/Konfigurationsdateien erzeugt, kein lokaler Serverstart, keine lokale DB-Installation – Zielsystem ist der externe Host.

10. Modularität für zukünftige Erweiterungen

• Neue Domänen (Medikamente, Lager, Prüfungen, weitere Ressourcentypen, Karte 11/Prompt 15/24) werden als zusätzliche Service-/Router-Module ergänzt, ohne Kernmodule (Kontrolle/Fehlbestand/Mindermenge) anzufassen — direkte Umsetzung des Designziels aus Prompt 06.

11. Hardware-Anforderungen

Endgeräte (Mitarbeiter/Verantwortliche)

• Tablet/Smartphone mit Kamera (Barcode-Scan Code128 per Kamera, Prompt 17/Karte 10) – kein Spezialgerät, handelsübliches Gerät mit aktuellem Browser reicht (PWA-Ansatz).
• PC/Notebook für Dashboard/Administration – normaler Browser reicht, keine Installation nötig.

Server (extern, Zielsystem)

• Linux-VPS, Größe skaliert mit Nutzerzahl; für V1/kleine-mittlere Organisation grobe Hausnummer 2 vCPU/4GB RAM, konkret erst bei Umsetzung/Lasttest zu verifizieren.
• PostgreSQL auf demselben oder separatem Server.
• Kein Docker-Zwang (siehe 9.), Backend läuft direkt als Python-Prozess (Uvicorn/systemd).

Sonstiges

• Label-Drucker für QR-/Barcode-Labels (Karte 10, Roadmap Prompt 24) – Anforderung an Druckqualität/Kontrast dort bereits vermerkt.
• Kein USB-Handscanner nötig (Entscheidung Karte 10: Kamera-Scan statt Hardware-Scanner).

Satelliten-Server (Karte 13, Erweiterung)

• Kleiner lokaler Rechner/Mini-PC vor Ort (Einsatzort/Wache), betreibt dieselbe Software wie der Hauptserver (identisches Backend+DB-Schema), keine reduzierte Sonderversion.
• Muss vor Trennung mit den relevanten Stammdaten (Materialstamm, Vorlagen der betroffenen Objekte) bestückt sein – Vorbereitung Teil der Auslagerung, Detail offen (siehe Karte 13).
• Anforderung eher gering (lokales Mehrbenutzer-Team, kein großer Lastfall) – z. B. Mini-PC/NUC-Klasse ausreichend, konkrete Spezifikation bei Umsetzung.

12. Mehrserver-Architektur: Hauptserver + Satelliten (Karte 13)

Ergänzung zur reinen Ein-Server-Architektur (Punkt 9): Neben dem zentralen Hauptserver können Satelliten-Server betrieben werden – vollwertige Klone derselben Anwendung, temporär vom Hauptserver getrennt einsetzbar (Details fachlich in 17_mobile_offline Punkt 7, 13_satelliten_server).

• Objekt-Zuordnung als Kernmechanismus: jedes Objekt trägt ein Feld „aktuell zuständiger Server" (Hauptserver oder eine bestimmte Satelliten-ID). Nur der zuständige Server nimmt Schreiboperationen für dieses Objekt an – der jeweils andere lehnt sie ab bzw. zeigt es nicht als bearbeitbar.
• Eindeutige IDs von Anfang an: damit am Satelliten neu erzeugte Datensätze (Kontrollen, Fehlbestände, Nachfüllungen, Historie) beim Zusammenführen nicht mit Hauptserver-IDs kollidieren, werden global eindeutige IDs verwendet (z. B. UUID statt fortlaufender Integer-Primärschlüssel für sync-relevante Tabellen) – Abweichung vom reinen SERIAL-Schema aus Prompt 20 für genau diese Tabellen, bei Umsetzung zu berücksichtigen.
• Synchronisation: bei wiederhergestellter Verbindung überträgt der Satellit neu entstandene Datensätze per Insert UND geänderte, bereits vor der Auslagerung existierende Zeilen (Objektpositionen, Fehlbestände, Mindermengen-Genehmigungen) per Upsert an den Hauptserver – kein reiner Append-Vorgang (Details/SQL siehe 20_datenbank_schema Punkt 10). Kein Merge/Konfliktlösung nötig, da Objekt-Zuordnung Überschneidungen strukturell ausschließt. Danach wird die Objekt-Zuordnung wieder auf den Hauptserver zurückgesetzt.
• Kein Zeitlimit: Architektur darf keine Annahme über maximale Trennungsdauer treffen (Nutzervorgabe) – Synchronisationslogik muss auch nach Tagen/unbestimmter Zeit funktionieren.

Referenzen

Bezug: alle Ergebnisse 01-18, 13_satelliten_server