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

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), supports user search and profile updates.")
-        Component(userCtrl, "UserController", "Spring MVC — /api/users", "Returns current user (/me). Creates and deletes users (requires ADMIN_USER permission).")
         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(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 (persons, documents) if DB is empty.")
+        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 email. Supports search by email or display name.")
-        Component(userRepo, "AppUserRepository", "Spring Data JPA", "Finds users by username. Used by Spring Security and UserService.")
         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