From d2a4707c3e2fb7f799ab4ddd98959b5a06a79c63 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Wed, 6 May 2026 21:23:26 +0200
Subject: [PATCH] docs(c4): add L1 context and L2 containers as C4-PlantUML
 files

---
 docs/architecture/c4/l1-context.puml    | 16 ++++++++++++++
 docs/architecture/c4/l2-containers.puml | 28 +++++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 docs/architecture/c4/l1-context.puml
 create mode 100644 docs/architecture/c4/l2-containers.puml

diff --git a/docs/architecture/c4/l1-context.puml b/docs/architecture/c4/l1-context.puml
new file mode 100644
index 00000000..8d2efb8f
--- /dev/null
+++ b/docs/architecture/c4/l1-context.puml
@@ -0,0 +1,16 @@
+@startuml
+!include <C4/C4_Context>
+
+title System Context: Familienarchiv
+
+Person(admin, "Administrator", "Manages users, triggers bulk imports, reviews and transcribes documents")
+Person(member, "Family Member", "Access by administrator invite. Searches, browses, reads, and transcribes archived documents.")
+
+System(familienarchiv, "Familienarchiv", "Web application for digitising, organising, and searching family documents")
+System_Ext(mail, "Email Service", "SMTP server. Delivers notification emails (mentions, replies) and password-reset links.")
+
+Rel(admin, familienarchiv, "Manages via browser", "HTTPS")
+Rel(member, familienarchiv, "Searches, reads, and transcribes via browser", "HTTPS")
+Rel(familienarchiv, mail, "Sends notification and password-reset emails (optional)", "SMTP")
+
+@enduml
diff --git a/docs/architecture/c4/l2-containers.puml b/docs/architecture/c4/l2-containers.puml
new file mode 100644
index 00000000..bd187bca
--- /dev/null
+++ b/docs/architecture/c4/l2-containers.puml
@@ -0,0 +1,28 @@
+@startuml
+!include <C4/C4_Container>
+
+title Container Diagram: Familienarchiv
+
+Person(user, "User", "Admin or family member")
+System_Ext(mail, "Email Service", "SMTP server. Delivers notification and password-reset emails.")
+
+System_Boundary(archiv, "Familienarchiv (Docker Compose)") {
+    Container(frontend, "Web Frontend", "SvelteKit / Node.js", "Server-side rendered UI. Handles auth session cookies, document search and viewer, transcription editor, annotation layer, family tree (Stammbaum), stories (Geschichten), activity feed (Chronik), enrichment workflow, and admin panel.")
+    Container(backend, "API Backend", "Spring Boot 4 / Java 21 / Jetty", "REST API. Implements document management, search, user auth, file upload/download, transcription, OCR orchestration, and SSE notifications.")
+    Container(ocr, "OCR Service", "Python FastAPI / port 8000", "Handwritten text recognition (HTR) and OCR microservice. Single-node by design — see ADR-001. Reachable only on the internal Docker network; no external port exposed.")
+    ContainerDb(db, "Relational Database", "PostgreSQL 16", "Stores document metadata, persons, users, permission groups, tags, transcription blocks, audit log, and Spring Session data.")
+    ContainerDb(storage, "Object Storage", "MinIO (S3-compatible)", "Stores the actual document files (PDFs, scans). Objects keyed as documents/{UUID}_{filename}.")
+    Container(mc, "Bucket Init Helper", "MinIO Client (mc)", "One-shot container on startup. Creates the archive bucket with private access policy.")
+}
+
+Rel(user, frontend, "Uses", "HTTPS / Browser")
+Rel(frontend, backend, "API requests with Basic Auth token", "HTTP / REST / JSON")
+Rel(backend, user, "SSE notifications (server-sent events)", "HTTP / SSE — direct backend-to-browser")
+Rel(backend, db, "Reads and writes metadata and sessions", "JDBC / SQL")
+Rel(backend, storage, "Uploads and streams document files", "HTTP / S3 API (AWS SDK v2)")
+Rel(backend, ocr, "OCR job requests with presigned MinIO URL", "HTTP / REST / JSON")
+Rel(backend, mail, "Sends notification and password-reset emails (optional)", "SMTP")
+Rel(ocr, storage, "Fetches PDF via presigned URL", "HTTP / S3 presigned")
+Rel(mc, storage, "Creates bucket on startup", "MinIO Client CLI")
+
+@enduml