# tonylimps/unifs-backend architecture

> Architecture diagram of the GitHub repository tonylimps/unifs-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tonylimps/unifs-backend
- Repository: https://github.com/tonylimps/unifs-backend

## Overview

UniFS-Backend is a Spring Boot API for public-key challenge registration and login, JWT-authenticated user profile operations, and persistence of users and rooms. The main workflow runs from HTTP endpoints through services: registration/login issue and verify challenges, update or create user records, then return JWTs; later requests pass JWT security filtering before user operations. The README documents users, rooms, and their membership schema, but the tree shows no room-management service or controller. Relationships below are limited to indexed source references and documented schema; room workflow wiring is not evidenced.

Main entry points: [`src/main/java/org/tonylimps/unifs/service/RegisterService.java`](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/service/RegisterService.java) (Registration service), [`src/main/java/org/tonylimps/unifs/service/LoginService.java`](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/service/LoginService.java) (Login service), [`src/main/java/org/tonylimps/unifs/mapper/UserMapper.java`](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/mapper/UserMapper.java) (User mapper), [`src/main/java/org/tonylimps/unifs/exception/BusinessException.java`](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/exception/BusinessException.java) (Business errors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_registration["Registration routes"]
  node_login["Login routes"]
  node_user_routes["User routes"]
  node_auth_requests["Auth request DTOs"]
  node_auth_responses["Auth response DTOs"]
  node_user_dtos["User DTOs"]
end

subgraph group_auth["Authentication"]
  node_registration_service["Registration service"]
  node_login_service["Login service<br/>[LoginService.java]"]
  node_sessions["Auth sessions<br/>[AuthSession.java]"]
  node_passkey["Challenge verification<br/>[PassKeyUtil.java]"]
  node_jwt["JWT utility<br/>[JwtUtil.java]"]
  node_jwt_filter["JWT filter<br/>[JwtFilter.java]"]
  node_security["Security configuration"]
end

subgraph group_user["User operations"]
  node_user_service["User service<br/>[UserService.java]"]
end

subgraph group_data["Persistence and policy"]
  node_user_entity["User entity<br/>[User.java]"]
  node_room_entity["Room entity<br/>[Room.java]"]
  node_membership_entity["Room membership<br/>[UserRoom.java]"]
  node_user_mapper["User mapper<br/>[UserMapper.java]"]
  node_room_mapper["Room mapper<br/>[RoomMapper.java]"]
  node_membership_mapper["Membership mapper"]
  node_errors["Business errors"]
  node_error_handler["Error handler"]
end

node_client(("API client"))
node_database[("Relational database")]

node_client -->|"submits registration"| node_registration
node_client -->|"submits login"| node_login
node_client -.->|"requests profile"| node_user_routes
node_registration -->|"calls"| node_registration_service
node_login -->|"calls"| node_login_service
node_user_routes -->|"delegates to"| node_user_service
node_registration_service -->|"verifies challenge"| node_passkey
node_login_service -->|"verifies challenge"| node_passkey
node_registration_service -->|"stores session"| node_sessions
node_login_service -->|"stores session"| node_sessions
node_registration_service -->|"issues token"| node_jwt
node_login_service -->|"issues token"| node_jwt
node_registration_service -->|"inserts user"| node_user_mapper
node_login_service -->|"reads and updates"| node_user_mapper
node_user_service -->|"reads and writes"| node_user_mapper
node_registration_service -->|"creates"| node_user_entity
node_login_service -->|"uses"| node_user_entity
node_user_mapper -->|"maps"| node_user_entity
node_jwt_filter -->|"validates token"| node_jwt
node_security -->|"configures"| node_jwt_filter
node_user_mapper -.->|"persists users"| node_database
node_room_mapper -.->|"room persistence"| node_database
node_membership_mapper -.->|"membership persistence"| node_database
node_room_mapper -->|"maps"| node_room_entity
node_membership_mapper -->|"maps"| node_membership_entity
node_registration_service -->|"raises"| node_errors
node_login_service -->|"raises"| node_errors
node_user_service -->|"raises"| node_errors
node_error_handler -->|"handles"| node_errors

click node_registration "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/controller/RegisterController.java"
click node_login "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/controller/LoginController.java"
click node_user_routes "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/controller/UserController.java"
click node_auth_requests "https://github.com/tonylimps/unifs-backend/tree/main/src/main/java/org/tonylimps/unifs/model/dto/request"
click node_auth_responses "https://github.com/tonylimps/unifs-backend/tree/main/src/main/java/org/tonylimps/unifs/model/dto/response"
click node_user_dtos "https://github.com/tonylimps/unifs-backend/tree/main/src/main/java/org/tonylimps/unifs/model/dto"
click node_registration_service "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/service/RegisterService.java"
click node_login_service "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/service/LoginService.java"
click node_sessions "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/model/pojo/AuthSession.java"
click node_passkey "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/util/PassKeyUtil.java"
click node_jwt "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/util/JwtUtil.java"
click node_jwt_filter "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/config/JwtFilter.java"
click node_security "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/config/SecurityConfig.java"
click node_user_service "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/service/UserService.java"
click node_user_entity "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/model/entity/User.java"
click node_room_entity "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/model/entity/Room.java"
click node_membership_entity "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/model/entity/UserRoom.java"
click node_user_mapper "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/mapper/UserMapper.java"
click node_room_mapper "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/mapper/RoomMapper.java"
click node_membership_mapper "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/mapper/UserRoomMapper.java"
click node_errors "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/exception/BusinessException.java"
click node_error_handler "https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/exception/GlobalExceptionHandler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_registration,node_login,node_user_routes,node_auth_requests,node_auth_responses,node_user_dtos,node_client toneBlue
class node_registration_service,node_login_service,node_sessions,node_passkey,node_jwt,node_jwt_filter,node_security,node_database toneAmber
class node_user_service toneMint
class node_user_entity,node_room_entity,node_membership_entity,node_user_mapper,node_room_mapper,node_membership_mapper,node_errors,node_error_handler toneRose
```

## Components

### HTTP API

- [Registration routes](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/controller/RegisterController.java): `src/main/java/org/tonylimps/unifs/controller/RegisterController.java`
- [Login routes](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/controller/LoginController.java): `src/main/java/org/tonylimps/unifs/controller/LoginController.java`
- [User routes](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/controller/UserController.java): `src/main/java/org/tonylimps/unifs/controller/UserController.java`
- [Auth request DTOs](https://github.com/tonylimps/unifs-backend/tree/main/src/main/java/org/tonylimps/unifs/model/dto/request): `src/main/java/org/tonylimps/unifs/model/dto/request`
- [Auth response DTOs](https://github.com/tonylimps/unifs-backend/tree/main/src/main/java/org/tonylimps/unifs/model/dto/response): `src/main/java/org/tonylimps/unifs/model/dto/response`
- [User DTOs](https://github.com/tonylimps/unifs-backend/tree/main/src/main/java/org/tonylimps/unifs/model/dto): `src/main/java/org/tonylimps/unifs/model/dto`

### Authentication

- [Registration service](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/service/RegisterService.java): `src/main/java/org/tonylimps/unifs/service/RegisterService.java`
- [Login service](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/service/LoginService.java): `src/main/java/org/tonylimps/unifs/service/LoginService.java`
- [Auth sessions](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/model/pojo/AuthSession.java): `src/main/java/org/tonylimps/unifs/model/pojo/AuthSession.java`
- [Challenge verification](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/util/PassKeyUtil.java): `src/main/java/org/tonylimps/unifs/util/PassKeyUtil.java`
- [JWT utility](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/util/JwtUtil.java): `src/main/java/org/tonylimps/unifs/util/JwtUtil.java`
- [JWT filter](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/config/JwtFilter.java): `src/main/java/org/tonylimps/unifs/config/JwtFilter.java`
- [Security configuration](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/config/SecurityConfig.java): `src/main/java/org/tonylimps/unifs/config/SecurityConfig.java`

### User operations

- [User service](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/service/UserService.java): `src/main/java/org/tonylimps/unifs/service/UserService.java`

### Persistence and policy

- [User entity](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/model/entity/User.java): `src/main/java/org/tonylimps/unifs/model/entity/User.java`
- [Room entity](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/model/entity/Room.java): `src/main/java/org/tonylimps/unifs/model/entity/Room.java`
- [Room membership](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/model/entity/UserRoom.java): `src/main/java/org/tonylimps/unifs/model/entity/UserRoom.java`
- [User mapper](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/mapper/UserMapper.java): `src/main/java/org/tonylimps/unifs/mapper/UserMapper.java`
- [Room mapper](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/mapper/RoomMapper.java): `src/main/java/org/tonylimps/unifs/mapper/RoomMapper.java`
- [Membership mapper](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/mapper/UserRoomMapper.java): `src/main/java/org/tonylimps/unifs/mapper/UserRoomMapper.java`
- [Business errors](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/exception/BusinessException.java): `src/main/java/org/tonylimps/unifs/exception/BusinessException.java`
- [Error handler](https://github.com/tonylimps/unifs-backend/blob/main/src/main/java/org/tonylimps/unifs/exception/GlobalExceptionHandler.java): `src/main/java/org/tonylimps/unifs/exception/GlobalExceptionHandler.java`

### Other components

- **API client**
- **Relational database**

## Connections

- API client → Registration routes: submits registration (evidence: `src/main/java/org/tonylimps/unifs/controller/RegisterController.java`)
- API client → Login routes: submits login (evidence: `src/main/java/org/tonylimps/unifs/controller/LoginController.java`)
- API client → User routes: requests profile
- Registration routes → Registration service: calls (evidence: `src/main/java/org/tonylimps/unifs/controller/RegisterController.java`)
- Login routes → Login service: calls (evidence: `src/main/java/org/tonylimps/unifs/controller/LoginController.java`)
- User routes → User service: delegates to (evidence: `src/main/java/org/tonylimps/unifs/controller/UserController.java`)
- Registration service → Challenge verification: verifies challenge (evidence: `src/main/java/org/tonylimps/unifs/service/RegisterService.java`)
- Login service → Challenge verification: verifies challenge (evidence: `src/main/java/org/tonylimps/unifs/service/LoginService.java`)
- Registration service → Auth sessions: stores session (evidence: `src/main/java/org/tonylimps/unifs/service/RegisterService.java`)
- Login service → Auth sessions: stores session (evidence: `src/main/java/org/tonylimps/unifs/service/LoginService.java`)
- Registration service → JWT utility: issues token (evidence: `src/main/java/org/tonylimps/unifs/service/RegisterService.java`)
- Login service → JWT utility: issues token (evidence: `src/main/java/org/tonylimps/unifs/service/LoginService.java`)
- Registration service → User mapper: inserts user (evidence: `src/main/java/org/tonylimps/unifs/service/RegisterService.java`)
- Login service → User mapper: reads and updates (evidence: `src/main/java/org/tonylimps/unifs/service/LoginService.java`)
- User service → User mapper: reads and writes (evidence: `src/main/java/org/tonylimps/unifs/service/UserService.java`)
- Registration service → User entity: creates (evidence: `src/main/java/org/tonylimps/unifs/service/RegisterService.java`)
- Login service → User entity: uses (evidence: `src/main/java/org/tonylimps/unifs/service/LoginService.java`)
- User mapper → User entity: maps (evidence: `src/main/java/org/tonylimps/unifs/mapper/UserMapper.java`)
- JWT filter → JWT utility: validates token (evidence: `src/main/java/org/tonylimps/unifs/config/JwtFilter.java`)
- Security configuration → JWT filter: configures (evidence: `src/main/java/org/tonylimps/unifs/config/SecurityConfig.java`)
- User mapper → Relational database: persists users (evidence: `README.md`)
- Room mapper → Relational database: room persistence (evidence: `README.md`)
- Membership mapper → Relational database: membership persistence (evidence: `README.md`)
- Room mapper → Room entity: maps (evidence: `src/main/java/org/tonylimps/unifs/mapper/RoomMapper.java`)
- Membership mapper → Room membership: maps (evidence: `src/main/java/org/tonylimps/unifs/mapper/UserRoomMapper.java`)
- Registration service → Business errors: raises (evidence: `src/main/java/org/tonylimps/unifs/service/RegisterService.java`)
- Login service → Business errors: raises (evidence: `src/main/java/org/tonylimps/unifs/service/LoginService.java`)
- User service → Business errors: raises (evidence: `src/main/java/org/tonylimps/unifs/service/UserService.java`)
- Error handler → Business errors: handles (evidence: `src/main/java/org/tonylimps/unifs/exception/GlobalExceptionHandler.java`)
