# fabianoic/roster architecture

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

- Interactive diagram: https://gitdiagram.com/fabianoic/roster
- Repository: https://github.com/fabianoic/roster

## Overview

Roster is a standalone employee scheduling REST service, separate from the order, kitchen, and inventory event flow. Its principal workflow is an authenticated client request, permission and ownership checks, controller validation, domain service processing, and persistence. The domain includes staffing, shifts and stores, availability, time-off, and shift swaps; role-permission administration and self-issued JWT authentication support that workflow. The README documents the layered design and major capabilities; some controller and service links below rely on that documentation because their implementations were not sampled.

Main entry points: [`src/main/java/com/ficsolution/roster/web/controller`](https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/web/controller) (REST controllers), [`src/main/java/com/ficsolution/roster/service/EmployeeService.java`](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/EmployeeService.java) (Employee management), [`src/main/java/com/ficsolution/roster/model`](https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/model) (Scheduling domain), [`src/main/java/com/ficsolution/roster/service/ShiftService.java`](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/ShiftService.java) (Shift scheduling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and security"]
  node_auth["Login API"]
  node_jwt["JWT security<br/>[JwtConfig.java]"]
  node_security["Request authorization"]
  node_securityutil["Ownership checks<br/>[SecurityUtil.java]"]
  node_controllers["REST controllers"]
  node_dtos["Request and response DTOs"]
  node_errors["Exception mapping"]
end

subgraph group_people["People and policy"]
  node_employees["Employee management"]
  node_roles["Role permissions<br/>[RoleService.java]"]
end

subgraph group_scheduling["Scheduling operations"]
  node_availability["Availability"]
  node_shifts["Shift scheduling<br/>[ShiftService.java]"]
  node_swaps["Shift swaps"]
  node_timeoff["Time-off requests"]
  node_stores["Store management<br/>[StoreService.java]"]
end

subgraph group_persistence["Domain and persistence"]
  node_models["Scheduling domain"]
  node_repositories["JPA repositories"]
  node_database[("PostgreSQL")]
end

node_client(("HTTP client"))

node_client -->|"sends request"| node_security
node_security -->|"routes authorized"| node_controllers
node_client -->|"submits login"| node_auth
node_auth -->|"issues token"| node_jwt
node_controllers -->|"validates and maps"| node_dtos
node_controllers -->|"delegates"| node_employees
node_controllers -->|"delegates"| node_availability
node_controllers -->|"delegates"| node_timeoff
node_controllers -->|"delegates"| node_swaps
node_controllers -->|"delegates"| node_roles
node_controllers -->|"checks ownership"| node_securityutil
node_employees -->|"resolves role"| node_roles
node_swaps -->|"approves via"| node_shifts
node_shifts -->|"resolves assignee"| node_employees
node_shifts -->|"resolves location"| node_stores
node_availability -->|"resolves employee"| node_employees
node_timeoff -->|"uses employee"| node_employees
node_employees -->|"operates on"| node_models
node_roles -->|"operates on"| node_models
node_shifts -->|"operates on"| node_models
node_availability -->|"operates on"| node_models
node_swaps -->|"operates on"| node_models
node_timeoff -->|"operates on"| node_models
node_stores -->|"operates on"| node_models
node_employees -->|"queries and saves"| node_repositories
node_roles -->|"queries and saves"| node_repositories
node_shifts -->|"queries and saves"| node_repositories
node_repositories -->|"persists entities"| node_database
node_controllers -.->|"bubbles domain errors"| node_errors

click node_auth "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/web/controller/AuthController.java"
click node_jwt "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/config/JwtConfig.java"
click node_security "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/config/SecurityConfig.java"
click node_securityutil "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/security/SecurityUtil.java"
click node_employees "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/EmployeeService.java"
click node_roles "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/RoleService.java"
click node_availability "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/AvailabilityService.java"
click node_shifts "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/ShiftService.java"
click node_swaps "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/ShiftSwapRequestService.java"
click node_timeoff "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/TimeOffRequestService.java"
click node_stores "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/StoreService.java"
click node_controllers "https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/web/controller"
click node_dtos "https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/web/dto"
click node_models "https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/model"
click node_repositories "https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/repository"
click node_errors "https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/web/handler/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_auth,node_jwt,node_security,node_securityutil,node_controllers,node_dtos,node_errors,node_client toneBlue
class node_employees,node_roles toneAmber
class node_availability,node_shifts,node_swaps,node_timeoff,node_stores toneMint
class node_models,node_repositories,node_database toneRose
```

## Components

### Access and security

- [Login API](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/web/controller/AuthController.java): `src/main/java/com/ficsolution/roster/web/controller/AuthController.java`
- [JWT security](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/config/JwtConfig.java): `src/main/java/com/ficsolution/roster/config/JwtConfig.java`
- [Request authorization](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/config/SecurityConfig.java): `src/main/java/com/ficsolution/roster/config/SecurityConfig.java`
- [Ownership checks](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/security/SecurityUtil.java): `src/main/java/com/ficsolution/roster/security/SecurityUtil.java`
- [REST controllers](https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/web/controller): `src/main/java/com/ficsolution/roster/web/controller`
- [Request and response DTOs](https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/web/dto): `src/main/java/com/ficsolution/roster/web/dto`
- [Exception mapping](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/web/handler/GlobalExceptionHandler.java): `src/main/java/com/ficsolution/roster/web/handler/GlobalExceptionHandler.java`

### People and policy

- [Employee management](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/EmployeeService.java): `src/main/java/com/ficsolution/roster/service/EmployeeService.java`
- [Role permissions](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/RoleService.java): `src/main/java/com/ficsolution/roster/service/RoleService.java`

### Scheduling operations

- [Availability](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/AvailabilityService.java): `src/main/java/com/ficsolution/roster/service/AvailabilityService.java`
- [Shift scheduling](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/ShiftService.java): `src/main/java/com/ficsolution/roster/service/ShiftService.java`
- [Shift swaps](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/ShiftSwapRequestService.java): `src/main/java/com/ficsolution/roster/service/ShiftSwapRequestService.java`
- [Time-off requests](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/TimeOffRequestService.java): `src/main/java/com/ficsolution/roster/service/TimeOffRequestService.java`
- [Store management](https://github.com/fabianoic/roster/blob/main/src/main/java/com/ficsolution/roster/service/StoreService.java): `src/main/java/com/ficsolution/roster/service/StoreService.java`

### Domain and persistence

- [Scheduling domain](https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/model): `src/main/java/com/ficsolution/roster/model`
- [JPA repositories](https://github.com/fabianoic/roster/tree/main/src/main/java/com/ficsolution/roster/repository): `src/main/java/com/ficsolution/roster/repository`
- **PostgreSQL**

### Other components

- **HTTP client**

## Connections

- HTTP client → Request authorization: sends request
- Request authorization → REST controllers: routes authorized
- HTTP client → Login API: submits login
- Login API → JWT security: issues token
- REST controllers → Request and response DTOs: validates and maps (evidence: `src/main/java/com/ficsolution/roster/web/controller/EmployeeController.java`)
- REST controllers → Employee management: delegates (evidence: `src/main/java/com/ficsolution/roster/web/controller/EmployeeController.java`)
- REST controllers → Availability: delegates (evidence: `src/main/java/com/ficsolution/roster/web/controller/AvailabilityController.java`)
- REST controllers → Time-off requests: delegates (evidence: `src/main/java/com/ficsolution/roster/web/controller/TimeOffRequestController.java`)
- REST controllers → Shift swaps: delegates (evidence: `src/main/java/com/ficsolution/roster/web/controller/ShiftSwapRequestController.java`)
- REST controllers → Role permissions: delegates (evidence: `src/main/java/com/ficsolution/roster/web/controller/RoleController.java`)
- REST controllers → Ownership checks: checks ownership (evidence: `src/main/java/com/ficsolution/roster/web/controller/EmployeeController.java`)
- Employee management → Role permissions: resolves role (evidence: `src/main/java/com/ficsolution/roster/service/EmployeeService.java`)
- Shift swaps → Shift scheduling: approves via (evidence: `src/main/java/com/ficsolution/roster/service/ShiftSwapRequestService.java`)
- Shift scheduling → Employee management: resolves assignee (evidence: `src/main/java/com/ficsolution/roster/service/ShiftService.java`)
- Shift scheduling → Store management: resolves location (evidence: `src/main/java/com/ficsolution/roster/service/ShiftService.java`)
- Availability → Employee management: resolves employee (evidence: `src/main/java/com/ficsolution/roster/service/AvailabilityService.java`)
- Time-off requests → Employee management: uses employee (evidence: `src/main/java/com/ficsolution/roster/service/TimeOffRequestService.java`)
- Employee management → Scheduling domain: operates on (evidence: `src/main/java/com/ficsolution/roster/service/EmployeeService.java`)
- Role permissions → Scheduling domain: operates on (evidence: `src/main/java/com/ficsolution/roster/service/RoleService.java`)
- Shift scheduling → Scheduling domain: operates on (evidence: `src/main/java/com/ficsolution/roster/service/ShiftService.java`)
- Availability → Scheduling domain: operates on (evidence: `src/main/java/com/ficsolution/roster/service/AvailabilityService.java`)
- Shift swaps → Scheduling domain: operates on (evidence: `src/main/java/com/ficsolution/roster/service/ShiftSwapRequestService.java`)
- Time-off requests → Scheduling domain: operates on (evidence: `src/main/java/com/ficsolution/roster/service/TimeOffRequestService.java`)
- Store management → Scheduling domain: operates on (evidence: `src/main/java/com/ficsolution/roster/service/StoreService.java`)
- Employee management → JPA repositories: queries and saves (evidence: `src/main/java/com/ficsolution/roster/service/EmployeeService.java`)
- Role permissions → JPA repositories: queries and saves (evidence: `src/main/java/com/ficsolution/roster/service/RoleService.java`)
- Shift scheduling → JPA repositories: queries and saves (evidence: `src/main/java/com/ficsolution/roster/service/ShiftService.java`)
- JPA repositories → PostgreSQL: persists entities
- REST controllers → Exception mapping: bubbles domain errors
