diff --git a/docs/architecture/c4-diagrams.md b/docs/architecture/c4-diagrams.md index cfe88f68..6161aa01 100644 --- a/docs/architecture/c4-diagrams.md +++ b/docs/architecture/c4-diagrams.md @@ -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