# openkku/cp-examseat-backend architecture

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

- Interactive diagram: https://gitdiagram.com/openkku/cp-examseat-backend
- Repository: https://github.com/openkku/cp-examseat-backend

## Overview

CP Exam Seat is a Go JSON API for student exam-seat lookup, room rosters and layouts, statistics, and calendar feeds, with protected administrative data management. The main student workflow routes a request through a domain controller and service to exam data, then returns a view; room exploration also exposes cascading filter options. A separate import workflow extracts PDF, spreadsheet, or JSON seating data into SQLite, while reload refreshes in-memory data and response caches. The room-config tool edits room metadata and layouts. Unsampled capabilities and layer links follow the README; uncertain implementation details are omitted.

Main entry points: [`internal/controllers`](https://github.com/openkku/cp-examseat-backend/tree/main/internal/controllers) (API Controllers), [`internal/app/app.go`](https://github.com/openkku/cp-examseat-backend/blob/main/internal/app/app.go) (Application Wiring), [`internal/repositories/sqlite`](https://github.com/openkku/cp-examseat-backend/tree/main/internal/repositories/sqlite) (Exam Database), [`internal/services/exam_service.go`](https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/exam_service.go) (Exam Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Views"]
  node_routes["API Router<br/>[routes.go]"]
  node_controllers["API Controllers"]
  node_views["Response Views"]
  node_response_cache["Response Cache<br/>[cache.go]"]
  node_calendar["Calendar Feed"]
end

subgraph group_domain["Domain Services"]
  node_exam_service["Exam Service<br/>[exam_service.go]"]
  node_round_service["Round Service<br/>[round_service.go]"]
  node_stats_service["Statistics Service<br/>[stats_service.go]"]
  node_room_service["Room Service<br/>[room_service.go]"]
  node_models["Domain Models"]
  node_app["Application Wiring<br/>[app.go]"]
end

subgraph group_storage["Persistence"]
  node_sqlite[("Exam Database")]
  node_room_files["Room Files"]
end

subgraph group_admin["Administration"]
  node_ingest_service["Ingest Service<br/>[ingest_service.go]"]
  node_backup_service["Backup Service<br/>[backup_service.go]"]
  node_extractors["Seat Extractors"]
end

subgraph group_roomtool["Room Editor"]
  node_room_routes["Editor Router<br/>[routes.go]"]
  node_room_controller["Room Config API"]
  node_room_store["Room Config Store"]
  node_room_ui["Room Editor UI<br/>[App.tsx]"]
end

node_students(("Students"))
node_admin_users(("Administrators"))
node_editor_users(("Room Editors"))
node_migrate_cli["Migrate CLI<br/>[main.go]"]

node_students -->|"request"| node_routes
node_routes -->|"dispatches"| node_controllers
node_controllers -->|"queries exams"| node_exam_service
node_controllers -->|"queries rounds"| node_round_service
node_controllers -->|"queries stats"| node_stats_service
node_controllers -->|"gets rooms"| node_room_service
node_controllers -->|"renders response"| node_views
node_controllers -->|"serves cached"| node_response_cache
node_exam_service -->|"queries seats"| node_sqlite
node_exam_service -->|"checks layouts"| node_room_service
node_round_service -->|"loads rounds"| node_sqlite
node_stats_service -->|"reads exam data"| node_sqlite
node_stats_service -->|"builds analytics"| node_models
node_room_service -->|"loads catalog"| node_room_files
node_controllers -->|"serves calendar"| node_calendar
node_calendar -->|"gets schedules"| node_exam_service
node_admin_users -->|"admin request"| node_routes
node_controllers -->|"imports seats"| node_ingest_service
node_controllers -->|"manages backups"| node_backup_service
node_ingest_service -->|"extracts seats"| node_extractors
node_ingest_service -->|"replaces exam data"| node_sqlite
node_migrate_cli -->|"imports file"| node_ingest_service
node_backup_service -->|"backs up database"| node_sqlite
node_controllers -->|"requests reload"| node_app
node_app -->|"reloads rounds"| node_round_service
node_app -->|"refreshes stats"| node_stats_service
node_app -->|"replaces catalog"| node_room_service
node_app -->|"clears caches"| node_response_cache
node_editor_users -->|"edits layouts"| node_room_ui
node_room_ui -->|"calls JSON API"| node_room_routes
node_room_routes -->|"dispatches"| node_room_controller
node_room_controller -->|"reads and writes"| node_room_store
node_room_store -->|"updates room files"| node_room_files

click node_migrate_cli "https://github.com/openkku/cp-examseat-backend/blob/main/cmd/migrate/main.go"
click node_routes "https://github.com/openkku/cp-examseat-backend/blob/main/internal/routes/routes.go"
click node_controllers "https://github.com/openkku/cp-examseat-backend/tree/main/internal/controllers"
click node_views "https://github.com/openkku/cp-examseat-backend/tree/main/internal/views"
click node_response_cache "https://github.com/openkku/cp-examseat-backend/blob/main/internal/views/cache.go"
click node_exam_service "https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/exam_service.go"
click node_round_service "https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/round_service.go"
click node_stats_service "https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/stats_service.go"
click node_room_service "https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/room_service.go"
click node_ingest_service "https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/ingest_service.go"
click node_backup_service "https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/backup_service.go"
click node_models "https://github.com/openkku/cp-examseat-backend/tree/main/internal/models"
click node_sqlite "https://github.com/openkku/cp-examseat-backend/tree/main/internal/repositories/sqlite"
click node_room_files "https://github.com/openkku/cp-examseat-backend/tree/main/internal/repositories/filesystem"
click node_extractors "https://github.com/openkku/cp-examseat-backend/tree/main/internal/importers"
click node_app "https://github.com/openkku/cp-examseat-backend/blob/main/internal/app/app.go"
click node_room_routes "https://github.com/openkku/cp-examseat-backend/blob/main/internal/routes/routes.go"
click node_room_controller "https://github.com/openkku/cp-examseat-backend/blob/main/internal/controllers/room_config_controller.go"
click node_room_store "https://github.com/openkku/cp-examseat-backend/tree/main/internal/repositories/filesystem"
click node_room_ui "https://github.com/openkku/cp-examseat-backend/blob/main/cmd/room-config/frontend/src/App.tsx"
click node_calendar "https://github.com/openkku/cp-examseat-backend/blob/main/internal/controllers/calendar_controller.go"

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_routes,node_controllers,node_views,node_response_cache,node_calendar toneBlue
class node_exam_service,node_round_service,node_stats_service,node_room_service,node_models,node_app toneAmber
class node_sqlite,node_room_files toneMint
class node_ingest_service,node_backup_service,node_extractors toneRose
class node_room_routes,node_room_controller,node_room_store,node_room_ui,node_students,node_admin_users,node_editor_users toneIndigo
class node_migrate_cli toneTeal
```

## Components

### API and Views

- [API Router](https://github.com/openkku/cp-examseat-backend/blob/main/internal/routes/routes.go): `internal/routes/routes.go`
- [API Controllers](https://github.com/openkku/cp-examseat-backend/tree/main/internal/controllers): `internal/controllers`
- [Response Views](https://github.com/openkku/cp-examseat-backend/tree/main/internal/views): `internal/views`
- [Response Cache](https://github.com/openkku/cp-examseat-backend/blob/main/internal/views/cache.go): `internal/views/cache.go`
- [Calendar Feed](https://github.com/openkku/cp-examseat-backend/blob/main/internal/controllers/calendar_controller.go): `internal/controllers/calendar_controller.go`

### Domain Services

- [Exam Service](https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/exam_service.go): `internal/services/exam_service.go`
- [Round Service](https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/round_service.go): `internal/services/round_service.go`
- [Statistics Service](https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/stats_service.go): `internal/services/stats_service.go`
- [Room Service](https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/room_service.go): `internal/services/room_service.go`
- [Domain Models](https://github.com/openkku/cp-examseat-backend/tree/main/internal/models): `internal/models`
- [Application Wiring](https://github.com/openkku/cp-examseat-backend/blob/main/internal/app/app.go): `internal/app/app.go`

### Persistence

- [Exam Database](https://github.com/openkku/cp-examseat-backend/tree/main/internal/repositories/sqlite): `internal/repositories/sqlite`
- [Room Files](https://github.com/openkku/cp-examseat-backend/tree/main/internal/repositories/filesystem): `internal/repositories/filesystem`

### Administration

- [Ingest Service](https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/ingest_service.go): `internal/services/ingest_service.go`
- [Backup Service](https://github.com/openkku/cp-examseat-backend/blob/main/internal/services/backup_service.go): `internal/services/backup_service.go`
- [Seat Extractors](https://github.com/openkku/cp-examseat-backend/tree/main/internal/importers): `internal/importers`

### Room Editor

- [Editor Router](https://github.com/openkku/cp-examseat-backend/blob/main/internal/routes/routes.go): `internal/routes/routes.go`
- [Room Config API](https://github.com/openkku/cp-examseat-backend/blob/main/internal/controllers/room_config_controller.go): `internal/controllers/room_config_controller.go`
- [Room Config Store](https://github.com/openkku/cp-examseat-backend/tree/main/internal/repositories/filesystem): `internal/repositories/filesystem`
- [Room Editor UI](https://github.com/openkku/cp-examseat-backend/blob/main/cmd/room-config/frontend/src/App.tsx): `cmd/room-config/frontend/src/App.tsx`

### Other components

- **Students**
- **Administrators**
- **Room Editors**
- [Migrate CLI](https://github.com/openkku/cp-examseat-backend/blob/main/cmd/migrate/main.go): `cmd/migrate/main.go`

## Connections

- Students → API Router: request
- API Router → API Controllers: dispatches
- API Controllers → Exam Service: queries exams
- API Controllers → Round Service: queries rounds
- API Controllers → Statistics Service: queries stats
- API Controllers → Room Service: gets rooms
- API Controllers → Response Views: renders response
- API Controllers → Response Cache: serves cached
- Exam Service → Exam Database: queries seats
- Exam Service → Room Service: checks layouts
- Round Service → Exam Database: loads rounds
- Statistics Service → Exam Database: reads exam data
- Statistics Service → Domain Models: builds analytics
- Room Service → Room Files: loads catalog
- API Controllers → Calendar Feed: serves calendar
- Calendar Feed → Exam Service: gets schedules
- Administrators → API Router: admin request
- API Controllers → Ingest Service: imports seats
- API Controllers → Backup Service: manages backups
- Ingest Service → Seat Extractors: extracts seats
- Ingest Service → Exam Database: replaces exam data
- Migrate CLI → Ingest Service: imports file
- Backup Service → Exam Database: backs up database
- API Controllers → Application Wiring: requests reload
- Application Wiring → Round Service: reloads rounds
- Application Wiring → Statistics Service: refreshes stats
- Application Wiring → Room Service: replaces catalog
- Application Wiring → Response Cache: clears caches
- Room Editors → Room Editor UI: edits layouts
- Room Editor UI → Editor Router: calls JSON API
- Editor Router → Room Config API: dispatches
- Room Config API → Room Config Store: reads and writes
- Room Config Store → Room Files: updates room files