# linakoz/icts architecture

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

- Interactive diagram: https://gitdiagram.com/linakoz/icts
- Repository: https://github.com/linakoz/icts

## Overview

ICTS Europe Rostering System is a planner and manager application for maintaining security workers and contracts, importing CSV data, producing monthly shift rosters, resolving gaps, and approving rosters. The main workflow runs from authenticated browser actions through FastAPI routes into domain services and PostgreSQL; roster generation builds a scheduling problem and invokes the isolated CP-SAT process pool. The README documents these capabilities and runtime links, but many backend and roster UI implementations were not excerpted, so uncertain internal calls are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/main.py) (FastAPI application), [`frontend/src/App.tsx`](https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/App.tsx) (Browser UI), [`backend/app/rosters/router.py`](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/router.py) (Roster API), [`frontend/src/api/client.ts`](https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_web["Browser UI<br/>[App.tsx]"]
  node_auth_ui["Sign-in<br/>[LoginPage.tsx]"]
  node_worker_ui["Worker management<br/>[WorkersPage.tsx]"]
  node_import_ui["CSV import<br/>[ImportPage.tsx]"]
  node_roster_ui["Roster workspace<br/>[RosterPage.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_people["Workforce data"]
  node_worker_service["Worker records<br/>[router.py]"]
  node_contracts["Contract versions<br/>[resolve.py]"]
  node_change_service["Change impact<br/>[service.py]"]
  node_csv_service["CSV preview and apply<br/>[service.py]"]
end

subgraph group_roster["Roster lifecycle"]
  node_roster_routes["Roster API<br/>[router.py]"]
  node_problem_builder["Problem builder<br/>[problem_builder.py]"]
  node_solver["CP-SAT scheduling<br/>[types.py]"]
  node_roster_ops["Roster operations<br/>[generation.py]"]
  node_roster_data[("Roster storage<br/>[models.py]")]
  node_approval["Approval workflow<br/>[approval.py]"]
end

subgraph group_runtime["Backend runtime"]
  node_auth_api["Authentication routes<br/>[router.py]"]
  node_session["Session and roles<br/>[session.py]"]
  node_process_pool["Solver process pool<br/>[engine_pool.py]"]
  node_database[("PostgreSQL<br/>[db.py]")]
  node_backend["FastAPI application<br/>[main.py]"]
end

node_planner(("Planner or manager"))

node_planner -->|"uses"| node_web
node_web -->|"routes to"| node_auth_ui
node_web -->|"routes to"| node_worker_ui
node_web -->|"routes to"| node_import_ui
node_web -->|"routes to"| node_roster_ui
node_auth_ui -->|"requests through"| node_api_client
node_worker_ui -->|"requests through"| node_api_client
node_import_ui -.->|"requests through"| node_api_client
node_roster_ui -.->|"requests through"| node_api_client
node_api_client -->|"calls API"| node_backend
node_backend -->|"registers routes"| node_auth_api
node_backend -->|"registers routes"| node_worker_service
node_backend -->|"registers routes"| node_csv_service
node_backend -->|"registers routes"| node_roster_routes
node_auth_api -->|"uses"| node_session
node_worker_service -->|"applies changes"| node_change_service
node_worker_service -->|"resolves contracts"| node_contracts
node_csv_service -->|"previews and applies"| node_change_service
node_roster_routes -->|"builds problem"| node_problem_builder
node_roster_routes -->|"dispatches operations"| node_roster_ops
node_roster_routes -->|"delegates approval"| node_approval
node_roster_routes -->|"reads and writes"| node_roster_data
node_problem_builder -->|"resolves contracts"| node_contracts
node_problem_builder -->|"builds input types"| node_solver
node_roster_ops -->|"runs solve"| node_process_pool
node_process_pool -->|"executes CP-SAT"| node_solver
node_worker_service -.->|"reads and writes"| node_database
node_contracts -->|"stores versions"| node_database
node_roster_data -->|"stores assignments"| node_database
node_backend -->|"connects to"| node_database
node_backend -->|"starts pool"| node_process_pool

click node_web "https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/App.tsx"
click node_auth_ui "https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/auth/LoginPage.tsx"
click node_worker_ui "https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/features/workers/WorkersPage.tsx"
click node_import_ui "https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/features/imports/ImportPage.tsx"
click node_roster_ui "https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/features/roster/RosterPage.tsx"
click node_api_client "https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/api/client.ts"
click node_auth_api "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/auth/router.py"
click node_session "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/auth/session.py"
click node_worker_service "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/workers/router.py"
click node_contracts "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/contracts/resolve.py"
click node_change_service "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/changes/service.py"
click node_csv_service "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/csvio/service.py"
click node_roster_routes "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/router.py"
click node_problem_builder "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/problem_builder.py"
click node_solver "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/scheduling/types.py"
click node_process_pool "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/engine_pool.py"
click node_roster_ops "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/generation.py"
click node_roster_data "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/models.py"
click node_approval "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/approval.py"
click node_database "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/db.py"
click node_backend "https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/main.py"

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_web,node_auth_ui,node_worker_ui,node_import_ui,node_roster_ui,node_api_client toneBlue
class node_worker_service,node_contracts,node_change_service,node_csv_service toneAmber
class node_roster_routes,node_problem_builder,node_solver,node_roster_ops,node_roster_data,node_approval toneMint
class node_auth_api,node_session,node_process_pool,node_database,node_backend toneRose
class node_planner toneIndigo
```

## Components

### Web application

- [Browser UI](https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in](https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/auth/LoginPage.tsx): `frontend/src/auth/LoginPage.tsx`
- [Worker management](https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/features/workers/WorkersPage.tsx): `frontend/src/features/workers/WorkersPage.tsx`
- [CSV import](https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/features/imports/ImportPage.tsx): `frontend/src/features/imports/ImportPage.tsx`
- [Roster workspace](https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/features/roster/RosterPage.tsx): `frontend/src/features/roster/RosterPage.tsx`
- [API client](https://github.com/linakoz/icts/blob/feat/roster-calendar/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Workforce data

- [Worker records](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/workers/router.py): `backend/app/workers/router.py`
- [Contract versions](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/contracts/resolve.py): `backend/app/contracts/resolve.py`
- [Change impact](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/changes/service.py): `backend/app/changes/service.py`
- [CSV preview and apply](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/csvio/service.py): `backend/app/csvio/service.py`

### Roster lifecycle

- [Roster API](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/router.py): `backend/app/rosters/router.py`
- [Problem builder](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/problem_builder.py): `backend/app/rosters/problem_builder.py`
- [CP-SAT scheduling](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/scheduling/types.py): `backend/app/scheduling/types.py`
- [Roster operations](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/generation.py): `backend/app/rosters/generation.py`
- [Roster storage](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/models.py): `backend/app/rosters/models.py`
- [Approval workflow](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/rosters/approval.py): `backend/app/rosters/approval.py`

### Backend runtime

- [Authentication routes](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/auth/router.py): `backend/app/auth/router.py`
- [Session and roles](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/auth/session.py): `backend/app/auth/session.py`
- [Solver process pool](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/engine_pool.py): `backend/app/engine_pool.py`
- [PostgreSQL](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/db.py): `backend/app/db.py`
- [FastAPI application](https://github.com/linakoz/icts/blob/feat/roster-calendar/backend/app/main.py): `backend/app/main.py`

### Other components

- **Planner or manager**

## Connections

- Planner or manager → Browser UI: uses (evidence: `README.md`)
- Browser UI → Sign-in: routes to (evidence: `frontend/src/App.tsx`)
- Browser UI → Worker management: routes to (evidence: `frontend/src/App.tsx`)
- Browser UI → CSV import: routes to (evidence: `frontend/src/App.tsx`)
- Browser UI → Roster workspace: routes to (evidence: `frontend/src/App.tsx`)
- Sign-in → API client: requests through
- Worker management → API client: requests through
- CSV import → API client: requests through
- Roster workspace → API client: requests through
- API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Authentication routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Worker records: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → CSV preview and apply: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Roster API: registers routes (evidence: `backend/app/main.py`)
- Authentication routes → Session and roles: uses (evidence: `backend/app/auth/router.py`)
- Worker records → Change impact: applies changes (evidence: `backend/app/workers/router.py`)
- Worker records → Contract versions: resolves contracts (evidence: `backend/app/workers/router.py`)
- CSV preview and apply → Change impact: previews and applies (evidence: `backend/app/csvio/service.py`)
- Roster API → Problem builder: builds problem (evidence: `backend/app/rosters/router.py`)
- Roster API → Roster operations: dispatches operations (evidence: `backend/app/rosters/router.py`)
- Roster API → Approval workflow: delegates approval (evidence: `backend/app/rosters/router.py`)
- Roster API → Roster storage: reads and writes (evidence: `backend/app/rosters/router.py`)
- Problem builder → Contract versions: resolves contracts (evidence: `backend/app/rosters/problem_builder.py`)
- Problem builder → CP-SAT scheduling: builds input types (evidence: `backend/app/rosters/problem_builder.py`)
- Roster operations → Solver process pool: runs solve (evidence: `README.md`)
- Solver process pool → CP-SAT scheduling: executes CP-SAT (evidence: `README.md`)
- Worker records → PostgreSQL: reads and writes (evidence: `backend/app/workers/router.py`)
- Contract versions → PostgreSQL: stores versions
- Roster storage → PostgreSQL: stores assignments (evidence: `backend/app/rosters/models.py`)
- FastAPI application → PostgreSQL: connects to (evidence: `README.md`)
- FastAPI application → Solver process pool: starts pool (evidence: `README.md`)