From 1b55588aeea908d64c8bf35b26e9c31ce40df8bf Mon Sep 17 00:00:00 2001 From: Marcel Date: Wed, 6 May 2026 10:02:38 +0200 Subject: [PATCH] docs(c4): rewrite frontend 3b, add 3c people/stories/discovery, add 3d admin/help Co-Authored-By: Claude Sonnet 4.6 --- docs/architecture/c4-diagrams.md | 99 ++++++++++++++++++++++++++------ 1 file changed, 80 insertions(+), 19 deletions(-) diff --git a/docs/architecture/c4-diagrams.md b/docs/architecture/c4-diagrams.md index 9b82347b..f7e73608 100644 --- a/docs/architecture/c4-diagrams.md +++ b/docs/architecture/c4-diagrams.md @@ -361,43 +361,41 @@ C4Component Rel(resetPw, backend, "POST /api/auth/reset-password", "HTTP / JSON") ``` -### 3b — Pages & Shared Components +### 3b — Document Workflows -Application pages and reusable UI components. +Document search, viewing, editing, enrichment, and the shared components that support them. ```mermaid C4Component - title Component Diagram: Web Frontend — Pages & Shared Components + title Component Diagram: Web Frontend — Document Workflows Person(user, "User") Container(backend, "API Backend", "Spring Boot") System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") { - Component(homePage, "/ (Home / Search)", "SvelteKit Route", "Loader: parses URL search params (q, from, to, senderId, receiverId, tags), fetches /api/documents/search and /api/persons, returns results. Page: renders search form with full-text, date range, sender/receiver typeahead, tag filters. Displays paginated document list.") - Component(docDetail, "/documents/[id]", "SvelteKit Route", "Loader: fetches /api/documents/{id}. Handles 401 redirect to login, 404 error. Page: shows document metadata, file viewer (PDF/image inline), transcription, tags.") - Component(docEdit, "/documents/[id]/edit", "SvelteKit Route", "Form with PersonTypeahead for sender/receiver, TagInput for tags, date/location fields. Submits PUT to /api/documents/{id}.") - Component(persons, "/persons and /persons/[id]", "SvelteKit Routes", "Lists all persons. Detail page shows person metadata and all documents they sent.") - Component(conversations, "/conversations", "SvelteKit Route", "Selects two persons via PersonTypeahead, fetches /api/documents/conversation, displays chronological exchange.") - Component(adminPage, "/admin", "SvelteKit Route", "User management UI (create/delete users). Excel import trigger button (calls /api/admin/trigger-import).") - - Component(apiPersons, "/api/persons (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/persons?q=... to backend. Used by PersonTypeahead for typeahead suggestions.") - Component(apiTags, "/api/tags (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/tags to backend. Used by TagInput for autocomplete.") + Component(homePage, "/ (Home / Search)", "SvelteKit Route", "Loader: parses URL params (q, from, to, senderId, receiverId, tags), fetches /api/documents/search and /api/persons. Renders search form with full-text, date range, sender/receiver typeahead, and tag filters.") + Component(docDetail, "/documents/[id]", "SvelteKit Route", "Loader: GET /api/documents/{id}. Page: metadata panel, inline file viewer, transcription editor, annotation layer, and comment thread.") + Component(docEdit, "/documents/[id]/edit", "SvelteKit Route", "Edit form with PersonTypeahead, TagInput, date/location fields. Form action: PUT /api/documents/{id}.") + Component(docNew, "/documents/new", "SvelteKit Route", "Upload form for a new document. Loader: GET /api/persons. Form action: POST /api/documents with multipart file.") + Component(docBulkEdit, "/documents/bulk-edit", "SvelteKit Route", "Multi-document metadata editor. Loader: GET /api/documents/incomplete. Requires WRITE_ALL (redirects otherwise). Action: PATCH /api/documents/batch.") + Component(enrichPage, "/enrich/[id]", "SvelteKit Route", "Guided enrichment workflow. Loader: GET /api/documents/{id}. Progressively saves annotations and transcription blocks.") + Component(apiPersons, "/api/persons (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/persons?q=... to backend for PersonTypeahead suggestions.") + Component(apiTags, "/api/tags (SvelteKit API)", "SvelteKit Server Route", "Proxies GET /api/tags to backend for TagInput autocomplete.") Component(typeahead, "PersonTypeahead.svelte", "Svelte Component", "Async autocomplete for selecting a person. Debounces input, calls /api/persons?q=.") Component(tagInput, "TagInput.svelte", "Svelte Component", "Multi-tag input. Supports free-text entry and selecting existing tags from /api/tags.") } Rel(user, homePage, "Searches and browses", "HTTPS / Browser") - Rel(homePage, backend, "GET /api/documents/search", "HTTP / JSON") - Rel(homePage, backend, "GET /api/persons", "HTTP / JSON") - Rel(docDetail, backend, "GET /api/documents/{id}", "HTTP / JSON") - Rel(docDetail, backend, "GET /api/documents/{id}/file", "HTTP / Binary stream") + Rel(homePage, backend, "GET /api/documents/search, GET /api/persons", "HTTP / JSON") + Rel(docDetail, backend, "GET /api/documents/{id}, GET /api/documents/{id}/file", "HTTP / JSON + Binary") Rel(docEdit, backend, "PUT /api/documents/{id}", "HTTP / Multipart") - Rel(conversations, backend, "GET /api/documents/conversation", "HTTP / JSON") - Rel(adminPage, backend, "GET/POST/DELETE /api/users", "HTTP / JSON") - Rel(adminPage, backend, "POST /api/admin/trigger-import", "HTTP / JSON") + Rel(docNew, backend, "GET /api/persons, POST /api/documents", "HTTP / JSON + Multipart") + Rel(docBulkEdit, backend, "GET /api/documents/incomplete, PATCH /api/documents/batch", "HTTP / JSON") + Rel(enrichPage, backend, "GET/POST /api/transcription, POST /api/documents/{id}/annotations", "HTTP / JSON") Rel(homePage, typeahead, "Uses for sender/receiver filter", "") Rel(docEdit, typeahead, "Uses for sender/receiver selection", "") + Rel(docNew, typeahead, "Uses for sender selection", "") Rel(docEdit, tagInput, "Uses for tag management", "") Rel(typeahead, apiPersons, "Fetches suggestions", "HTTP") Rel(tagInput, apiTags, "Fetches existing tags", "HTTP") @@ -405,6 +403,69 @@ C4Component Rel(apiTags, backend, "GET /api/tags", "HTTP / JSON") ``` +### 3c — People, Stories & Discovery + +Person directory, bilateral conversations, activity feed, stories, family tree, and user profiles. + +```mermaid +C4Component + title Component Diagram: Web Frontend — People, Stories & Discovery + + Person(user, "User") + Container(backend, "API Backend", "Spring Boot") + + System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") { + Component(personsPage, "/persons and /persons/[id]", "SvelteKit Routes", "Person directory and detail. Detail: metadata, document list sent/received, correspondents, explicit and inferred family relationships.") + Component(personEdit, "/persons/[id]/edit and /persons/new", "SvelteKit Routes", "Create and edit person forms. Edit: metadata, aliases, explicit relationships. Actions: PUT/POST /api/persons.") + Component(briefwechsel, "/briefwechsel", "SvelteKit Route", "Bilateral conversation timeline. Selects two persons via PersonTypeahead, fetches GET /api/documents/conversation, displays chronological exchange.") + Component(aktivitaeten, "/aktivitaeten", "SvelteKit Route", "Unified activity feed (Chronik). Loader: GET /api/dashboard/activity and GET /api/notifications?read=false.") + Component(geschichten, "/geschichten and /geschichten/[id]", "SvelteKit Routes", "Story list and detail pages. Loader: GET /api/geschichten?status=PUBLISHED.") + Component(geschichtenEdit, "/geschichten/[id]/edit and /geschichten/new", "SvelteKit Routes", "Story editor with rich text, person and document linking. Actions: PUT/POST /api/geschichten. Requires BLOG_WRITE permission.") + Component(stammbaum, "/stammbaum", "SvelteKit Route", "Family tree visualisation. Loader: GET /api/network (nodes + edges). Renders interactive D3-based Stammbaum.") + Component(profilePage, "/profile", "SvelteKit Route", "Current user profile settings. Loader: GET /api/users/me/notification-preferences. Actions: update name/password and notification preferences.") + Component(userProfile, "/users/[id]", "SvelteKit Route", "Public user profile view. Loader: GET /api/users/{id}.") + } + + Rel(user, personsPage, "Browses family members", "HTTPS / Browser") + Rel(personsPage, backend, "GET /api/persons, GET /api/persons/{id}", "HTTP / JSON") + Rel(personEdit, backend, "GET /api/persons/{id}, PUT /api/persons/{id}, POST /api/persons", "HTTP / JSON") + Rel(briefwechsel, backend, "GET /api/documents/conversation", "HTTP / JSON") + Rel(aktivitaeten, backend, "GET /api/dashboard/activity, GET /api/notifications", "HTTP / JSON") + Rel(geschichten, backend, "GET /api/geschichten", "HTTP / JSON") + Rel(geschichtenEdit, backend, "GET/PUT/POST /api/geschichten", "HTTP / JSON") + Rel(stammbaum, backend, "GET /api/network", "HTTP / JSON") + Rel(profilePage, backend, "GET/PUT /api/users/me, notification-preferences", "HTTP / JSON") + Rel(userProfile, backend, "GET /api/users/{id}", "HTTP / JSON") +``` + +### 3d — Administration & Help + +Admin panel sub-routes and the transcription help guide. + +```mermaid +C4Component + title Component Diagram: Web Frontend — Administration & Help + + Person(admin, "Administrator") + Container(backend, "API Backend", "Spring Boot") + + System_Boundary(frontend, "Web Frontend (SvelteKit / SSR)") { + Component(adminUsers, "/admin/users, /admin/users/[id], /admin/users/new, /admin/invites", "SvelteKit Routes", "User directory, create/update/delete users, and manage invite codes. Requires ADMIN_USER permission.") + Component(adminGroups, "/admin/groups, /admin/groups/[id], /admin/groups/new", "SvelteKit Routes", "Permission group management: create/edit groups and their permission sets.") + Component(adminTags, "/admin/tags and /admin/tags/[id]", "SvelteKit Routes", "Tag administration: edit tag hierarchy, merge tags, delete subtrees.") + Component(adminOcr, "/admin/ocr and /admin/ocr/[personId]", "SvelteKit Routes", "Global and per-person OCR configuration. Manages script types and triggers sender model training.") + Component(adminSystem, "/admin/system", "SvelteKit Route", "System status panel. Triggers Excel/ODS mass import (POST /api/admin/trigger-import). Displays import state.") + Component(hilfe, "/hilfe/transkription", "SvelteKit Route", "Static transcription style guide for Kurrent and Sütterlin character recognition. No backend calls.") + } + + Rel(admin, adminUsers, "Manages users and invites", "HTTPS / Browser") + Rel(adminUsers, backend, "GET/POST/DELETE /api/users, POST /api/auth/invite", "HTTP / JSON") + Rel(adminGroups, backend, "GET/POST/PUT/DELETE /api/groups", "HTTP / JSON") + Rel(adminTags, backend, "GET/PUT/DELETE /api/tags", "HTTP / JSON") + Rel(adminOcr, backend, "GET/POST /api/ocr (global config and sender training)", "HTTP / JSON") + Rel(adminSystem, backend, "POST /api/admin/trigger-import, GET /api/admin/import-status", "HTTP / JSON") +``` + --- ## Authentication Flow