marcel/familienarchiv
1
0
Fork 0
Code Issues 125 Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs(c4): restructure 3c users/groups, add 3c.2 persons and family graph

Browse Source
This commit is contained in:
Marcel
2026-05-06 09:57:39 +02:00
committed by marcel
parent 63f00ce0a0
commit 3608a9723a
1 changed files with 49 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/architecture/c4-diagrams.md
View File

@@ -167,49 +167,83 @@ C4Component
Rel(transcriptionQueueSvc, db, "Queue projection queries", "JDBC")
```
### 3c — People, Users & Group Administration
### 3c — Users, Groups & Administration
Person, user, and group management, including startup seed data.
User lifecycle, permission groups, tag management, and authentication endpoints.
```mermaid
C4Component
title Component Diagram: API Backend — People, Users & Group Administration
title Component Diagram: API Backend — Users, Groups & Administration
Container(frontend, "Web Frontend", "SvelteKit")
ContainerDb(db, "PostgreSQL")
System_Boundary(backend, "API Backend (Spring Boot)") {
Component(personCtrl, "PersonController", "Spring MVC — /api/persons", "Lists and searches family members. Also returns all documents sent by a person.")
Component(userCtrl, "UserController", "Spring MVC — /api/users", "Returns current user (/me). Creates and deletes users (requires ADMIN_USER permission).")
Component(userCtrl, "UserController", "Spring MVC — /api/users", "Returns current user (/me), creates and deletes users (requires ADMIN_USER), supports user search and profile updates.")
Component(groupCtrl, "GroupController", "Spring MVC — /api/groups", "Lists and manages permission groups.")
Component(tagCtrl, "TagController", "Spring MVC — /api/tags", "Lists tags for typeahead.")
Component(tagCtrl, "TagController", "Spring MVC — /api/tags", "Lists tags for typeahead, supports tag merge, tree structure, and subtree deletion.")
Component(inviteCtrl, "InviteController", "Spring MVC — /api/auth/invite", "Creates invite codes and validates them at registration time. Rate-limited via WebConfig interceptor.")
Component(authCtrl, "AuthController", "Spring MVC — /api/auth", "Handles user registration (POST /register) and password reset token endpoints (/forgot-password, /reset-password).")
Component(userSvc, "UserService", "Spring Service", "User CRUD. Encodes passwords with BCrypt. Assigns users to permission groups.")
Component(dataInit, "DataInitializer", "CommandLineRunner", "On startup: creates default admin user and groups if none exist. Seeds test data (persons, documents) if DB is empty.")
Component(userSvc, "UserService", "Spring Service", "User CRUD with BCrypt password encoding, group assignment, and audit logging. Orchestrates invite-based registration and password reset tokens.")
Component(dataInit, "DataInitializer", "CommandLineRunner", "On startup: creates default admin user and groups if none exist. Seeds test data if DB is empty.")
Component(personRepo, "PersonRepository", "Spring Data JPA", "Lists all persons sorted by last name. Supports name search for typeahead.")
Component(userRepo, "AppUserRepository", "Spring Data JPA", "Finds users by username. Used by Spring Security and UserService.")
Component(userRepo, "AppUserRepository", "Spring Data JPA", "Finds users by email. Supports search by email or display name.")
Component(groupRepo, "UserGroupRepository", "Spring Data JPA", "Manages permission groups.")
Component(tagRepo, "TagRepository", "Spring Data JPA", "Finds or creates tags by name (case-insensitive).")
Component(tagRepo, "TagRepository", "Spring Data JPA", "Finds or creates tags by name (case-insensitive). Supports recursive ancestor/descendant CTE queries and merge/reparent helpers.")
}
Rel(frontend, personCtrl, "Person requests", "HTTP / JSON")
Rel(frontend, userCtrl, "User requests", "HTTP / JSON")
Rel(frontend, groupCtrl, "Group requests", "HTTP / JSON")
Rel(frontend, tagCtrl, "Tag requests", "HTTP / JSON")
Rel(personCtrl, personRepo, "Reads persons", "")
Rel(frontend, inviteCtrl, "Invite validation", "HTTP / JSON")
Rel(frontend, authCtrl, "Registration and password reset", "HTTP / JSON")
Rel(userCtrl, userSvc, "Delegates to", "")
Rel(groupCtrl, groupRepo, "Reads / writes groups", "")
Rel(tagCtrl, tagRepo, "Lists tags", "")
Rel(tagCtrl, tagRepo, "Reads / writes tags", "")
Rel(inviteCtrl, userSvc, "Creates and validates invites", "")
Rel(authCtrl, userSvc, "Registers users, resets passwords", "")
Rel(userSvc, userRepo, "Reads / writes users", "")
Rel(userSvc, groupRepo, "Assigns groups", "")
Rel(dataInit, db, "Seeds initial data", "JDBC")
Rel(personRepo, db, "SQL queries", "JDBC")
Rel(userRepo, db, "SQL queries", "JDBC")
Rel(groupRepo, db, "SQL queries", "JDBC")
Rel(tagRepo, db, "SQL queries", "JDBC")
```
### 3c.2 — Persons & Family Graph
Person management including family relationship modelling and transitive inference.
```mermaid
C4Component
title Component Diagram: API Backend — Persons & Family Graph
Container(frontend, "Web Frontend", "SvelteKit")
ContainerDb(db, "PostgreSQL")
System_Boundary(backend, "API Backend (Spring Boot)") {
Component(personCtrl, "PersonController", "Spring MVC — /api/persons", "Lists and searches family members. Returns documents sent by or received by a person, correspondent suggestions, and person summary with document counts.")
Component(relCtrl, "RelationshipController", "Spring MVC — /api/network, /api/persons/{id}/relationships", "CRUD for explicit person relationships and the full family network graph (nodes + edges) used by the Stammbaum view.")
Component(personSvc, "PersonService", "Spring Service", "Person CRUD, alias management, and merge operations (reassigns all document sender/receiver references before deleting duplicate persons).")
Component(relSvc, "RelationshipService", "Spring Service", "Manages explicit directional family relationships (PARENT_OF, SPOUSE_OF, SIBLING_OF, etc.) with optional date ranges and notes.")
Component(relInference, "RelationshipInferenceService", "Spring Service", "Computes transitive family relationships from explicit edges to infer grandparent/grandchild, aunt/uncle, and other extended-family links for the network graph.")
Component(personRepo, "PersonRepository", "Spring Data JPA", "Queries persons with name search (including aliases), correspondent discovery, person summaries with document counts, and merge/reassignment helpers.")
}
Rel(frontend, personCtrl, "Person requests", "HTTP / JSON")
Rel(frontend, relCtrl, "Relationship and graph requests", "HTTP / JSON")
Rel(personCtrl, personSvc, "Delegates to", "")
Rel(relCtrl, relSvc, "Delegates to", "")
Rel(relCtrl, relInference, "Queries inferred graph", "")
Rel(personSvc, personRepo, "Reads / writes persons", "")
Rel(relSvc, db, "Reads / writes relationships", "JDBC")
Rel(relInference, db, "Reads relationships for inference", "JDBC")
Rel(personRepo, db, "SQL queries", "JDBC")
```
---
## Level 3 — Components: Web Frontend