# iqb-berlin/testcenter architecture

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

- Interactive diagram: https://gitdiagram.com/iqb-berlin/testcenter
- Repository: https://github.com/iqb-berlin/testcenter

## Overview

1. **What this repository is**
   - IQB-Testcenter is a multi-service platform for running tests and surveys.
   - It is not a single app: the repository contains the browser UI, a PHP backend API, a realtime broadcaster, a protected file server, deployment charts, and extensive test/data assets.

2. **Frontend: Angular single-page application**
   - `frontend/` is the main user-facing SPA, built with Angular.
   - It is split into feature areas that map directly to product roles and workflows: `test-controller`, `group-monitor`, `workspace-admin`, `superadmin`, `sys-check`, `study-monitor`, `attachment-manager`, plus shared login and shell components.
   - Route guards, interceptors, and shared services indicate the frontend is the orchestration layer that talks to backend APIs and websocket services rather than owning business data.

3. **Backend: PHP API and business logic**
   - `backend/` is a PHP service organized around `controller`, `dao`, `middleware`, `helper`, `files`, and `workspace`.
   - `routes.php`, `index.php`, and `initialize.php` suggest a classic HTTP API entrypoint that handles authentication, domain actions, workspace administration, session management, reporting, and file-related operations.
   - The backend is the source of truth for persisted domain state and also contains initialization/migration logic for upgrading installations.

4. **Realtime collaboration layer: broadcaster**
   - `broadcaster/` is a separate NestJS/TypeScript service focused on live session communication.
   - Its modules (`test-session`, `testee`, `monitor`, `system`, `command`) and `websocket.gateway.ts` show that it handles websocket events and distributes state changes to clients.
   - This service bridges backend-triggered events and frontend live views such as monitoring and active test sessions.

5. **Protected content delivery: file-server**
   - `file-server/` is an Nginx-based service with Lua auth hooks and Redis integration.
   - It appears to serve test resources, attachments, and other binary content under authorization, keeping large file delivery separate from the API.
   - This creates a clean boundary between metadata/state in the backend and downloadable content in the file layer.

6. **Shared contract and content model**
   - `common/` holds shared TypeScript interfaces used across frontend and broadcaster.
   - `definitions/` contains XML schemas and JSON definitions for domain objects such as booklets, units, testtakers, sys-check, mode options, and browser metadata.
   - These files are important because the system’s core content is XML/schema-driven, not just REST DTOs.

7. **Primary runtime flow**
   - A user enters via the frontend.
   - The frontend authenticates and then calls the backend for session/workspace/admin actions.
   - For live test state, the frontend also connects to the broadcaster for websocket updates.
   - For resources and uploads, the browser goes through the file-server, which enforces access control before serving content.

8. **Domain boundaries**
   - The product is divided into operational modes that match the front-end features: test execution, group monitoring, workspace administration, super-admin configuration, and system check.
   - The backend and broadcaster both model “test session” concepts, but with different responsibilities: backend persists and authorizes, broadcaster propagates runtime changes.
   - Workspace-level administration is a major boundary: workspaces own tests, files, results, and sys-check artifacts.

9. **Persistence and schema evolution**
   - `scripts/database/` contains the base schema plus versioned SQL patches, showing that database evolution is managed as an explicit migration stream.
   - `backend/test/initialization/` contains upgrade/install scenarios, confirming that compatibility across many installed versions is a first-class concern.
   - `backup/`, `secrets/`, and sample data directories indicate that deployments rely on filesystem-managed state in addition to the SQL database.

10. **Deployment topology**
   - The repo supports Docker Compose for local/dev/prod and Helm charts under `scripts/helm/testcenter/`.
   - The deployed stack includes backend, frontend, broadcaster, file-server, database, and a cache server, typically fronted by Traefik and optionally Longhorn storage in Kubernetes.
   - This means the architecture is service-oriented, with explicit reverse-proxy and storage concerns rather than a monolith.

11. **Testing strategy**
   - Backend: PHPUnit unit tests plus initialization/upgrade tests.
   - Frontend: Angular unit tests and Cypress-based end-to-end tests under `e2e/`.
   - Broadcaster: Jest/Nest tests.
   - The presence of many XML fixtures and sample data sets shows that test coverage is driven by realistic domain content, not just isolated mocks.

12. **Tooling and release/support infrastructure**
   - `scripts/` contains CI helpers, docs generation, interface generation, versioning, and migration scripts.
   - `docs/` is substantial and includes API specs, installation guides, and domain documentation, which implies the architecture is intended to be operated and upgraded by administrators, not just used by end users.
   - Overall, the repository is a coordinated multi-service system with strong separation between UI, persistent backend logic, realtime event propagation, and protected file serving.

Main entry points: [`backend`](https://github.com/iqb-berlin/testcenter/tree/master/backend) (Backend API), [`frontend`](https://github.com/iqb-berlin/testcenter/tree/master/frontend) (Frontend), [`broadcaster`](https://github.com/iqb-berlin/testcenter/tree/master/broadcaster) (Broadcaster), [`scripts/helm/testcenter`](https://github.com/iqb-berlin/testcenter/tree/master/scripts/helm/testcenter) (Deployment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_frontend["Frontend<br/>Angular SPA"]
  node_test_controller["Test Control<br/>exam flow"]
  node_group_monitor["Group Monitor<br/>live monitor"]
  node_workspace_admin["Workspace Admin<br/>workspace UI"]
  node_superadmin["Superadmin<br/>admin UI"]
  node_sys_check["Sys Check<br/>diagnostics UI"]
  node_shared_ui["Shared UI<br/>common components"]
end

subgraph group_services["Core Services"]
  node_backend[("Backend API<br/>PHP service")]
  node_backend_routes["API Routes<br/>HTTP routing<br/>[routes.php]"]
  node_backend_domain["Domain Logic<br/>controllers/DAO"]
  node_backend_init["Init & Upgrade<br/>migration boot<br/>[initialize.php]"]
  node_broadcaster(("Broadcaster<br/>NestJS realtime"))
  node_ws_gateway["Websocket Gateway<br/>ws transport"]
  node_session_rt["Session Realtime<br/>test-session live"]
  node_command_rt["Command API<br/>control channel"]
  node_file_server{{"File Server<br/>Nginx/Lua"}}
  node_file_auth["Auth Hooks<br/>nginx lua"]
end

subgraph group_shared["Shared Contracts"]
  node_contracts["Contracts<br/>shared types"]
  node_definitions["Definitions<br/>XML schemas"]
end

subgraph group_ops["Operations"]
  node_deployment["Deployment<br/>compose/helm"]
  node_database_migrations["DB Migrations<br/>sql patches"]
  node_docs["Docs"]
end

subgraph group_verification["Verification"]
  node_e2e["E2E Tests<br/>cypress"]
  node_backend_tests["Backend Tests<br/>phpunit"]
  node_sampledata["Sample Data<br/>fixtures"]
end

node_frontend -->|"API calls"| node_backend
node_frontend -->|"websockets"| node_broadcaster
node_frontend -->|"downloads/uploads"| node_file_server
node_frontend -->|"uses"| node_shared_ui
node_frontend -->|"types"| node_contracts
node_test_controller -->|"reuses"| node_shared_ui
node_group_monitor -->|"monitors"| node_broadcaster
node_workspace_admin -->|"manages"| node_backend
node_superadmin -->|"administers"| node_backend
node_sys_check -->|"reports"| node_backend
node_backend -->|"routes"| node_backend_routes
node_backend_routes -->|"dispatches"| node_backend_domain
node_backend -->|"boots/upgrades"| node_backend_init
node_backend -->|"schema updates"| node_database_migrations
node_broadcaster -->|"exposes"| node_ws_gateway
node_ws_gateway -->|"dispatches events"| node_session_rt
node_session_rt -->|"control flow"| node_command_rt
node_broadcaster -.->|"runtime state"| node_backend
node_file_server -->|"authenticates"| node_file_auth
node_deployment -->|"deploys"| node_frontend
node_deployment -->|"deploys"| node_backend
node_deployment -->|"deploys"| node_broadcaster
node_deployment -->|"deploys"| node_file_server
node_deployment -.->|"provisions"| node_database_migrations
node_docs -.->|"specifies"| node_backend
node_docs -.->|"guides"| node_frontend
node_e2e -->|"drives"| node_frontend
node_e2e -->|"integrates"| node_backend
node_e2e -->|"validates"| node_broadcaster
node_backend_tests -->|"verifies"| node_backend
node_backend_tests -->|"checks upgrades"| node_database_migrations
node_sampledata -.->|"conforms to"| node_definitions
node_sampledata -.->|"feeds"| node_e2e

click node_frontend "https://github.com/iqb-berlin/testcenter/tree/master/frontend"
click node_test_controller "https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/test-controller"
click node_group_monitor "https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/group-monitor"
click node_workspace_admin "https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/workspace-admin"
click node_superadmin "https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/superadmin"
click node_sys_check "https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/sys-check"
click node_shared_ui "https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/shared"
click node_backend "https://github.com/iqb-berlin/testcenter/tree/master/backend"
click node_backend_routes "https://github.com/iqb-berlin/testcenter/blob/master/backend/routes.php"
click node_backend_domain "https://github.com/iqb-berlin/testcenter/tree/master/backend/src"
click node_backend_init "https://github.com/iqb-berlin/testcenter/blob/master/backend/initialize.php"
click node_broadcaster "https://github.com/iqb-berlin/testcenter/tree/master/broadcaster"
click node_ws_gateway "https://github.com/iqb-berlin/testcenter/blob/master/broadcaster/src/common/websocket.gateway.ts"
click node_session_rt "https://github.com/iqb-berlin/testcenter/tree/master/broadcaster/src/test-session"
click node_command_rt "https://github.com/iqb-berlin/testcenter/tree/master/broadcaster/src/command"
click node_file_server "https://github.com/iqb-berlin/testcenter/tree/master/file-server"
click node_file_auth "https://github.com/iqb-berlin/testcenter/tree/master/file-server/auth"
click node_contracts "https://github.com/iqb-berlin/testcenter/tree/master/common"
click node_definitions "https://github.com/iqb-berlin/testcenter/tree/master/definitions"
click node_deployment "https://github.com/iqb-berlin/testcenter/tree/master/scripts/helm/testcenter"
click node_database_migrations "https://github.com/iqb-berlin/testcenter/tree/master/scripts/database"
click node_docs "https://github.com/iqb-berlin/testcenter/tree/master/docs"
click node_e2e "https://github.com/iqb-berlin/testcenter/tree/master/e2e"
click node_backend_tests "https://github.com/iqb-berlin/testcenter/tree/master/backend/test"
click node_sampledata "https://github.com/iqb-berlin/testcenter/tree/master/sampledata"

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_frontend,node_test_controller,node_group_monitor,node_workspace_admin,node_superadmin,node_sys_check,node_shared_ui toneBlue
class node_backend,node_backend_routes,node_backend_domain,node_backend_init,node_broadcaster,node_ws_gateway,node_session_rt,node_command_rt,node_file_server,node_file_auth toneAmber
class node_contracts,node_definitions toneMint
class node_deployment,node_database_migrations,node_docs toneRose
class node_e2e,node_backend_tests,node_sampledata toneIndigo
```

## Components

### Client UI

Browser-facing Angular application and its feature areas.

- [Frontend](https://github.com/iqb-berlin/testcenter/tree/master/frontend): Angular SPA · Main browser application coordinating login, roles, and live workflows. · `frontend`
- [Test Control](https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/test-controller): exam flow · Participant-facing test execution, navigation, and review logic. · `frontend/src/app/test-controller`
- [Group Monitor](https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/group-monitor): live monitor · Supervisor view for monitoring test sessions and applying controls. · `frontend/src/app/group-monitor`
- [Workspace Admin](https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/workspace-admin): workspace UI · Workspace-scoped management for tests, files, results, and sys-check data. · `frontend/src/app/workspace-admin`
- [Superadmin](https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/superadmin): admin UI · Global administration for users, workspaces, and settings. · `frontend/src/app/superadmin`
- [Sys Check](https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/sys-check): diagnostics UI · Client-side system check, questionnaire, network test, and report flow. · `frontend/src/app/sys-check`
- [Shared UI](https://github.com/iqb-berlin/testcenter/tree/master/frontend/src/app/shared): common components · Cross-cutting Angular components, services, interceptors, and view helpers. · `frontend/src/app/shared`

### Core Services

Backend API, realtime broadcaster, and protected file delivery.

- [Backend API](https://github.com/iqb-berlin/testcenter/tree/master/backend): PHP service · HTTP API entrypoint for authentication, persistence, workspace actions, and initialization. · `backend`
- [API Routes](https://github.com/iqb-berlin/testcenter/blob/master/backend/routes.php): HTTP routing · Top-level request routing and bootstrap for backend endpoints. · `backend/routes.php`
- [Domain Logic](https://github.com/iqb-berlin/testcenter/tree/master/backend/src): controllers/DAO · Controllers, data access, middleware, helpers, and workspace report logic. · `backend/src`
- [Init & Upgrade](https://github.com/iqb-berlin/testcenter/blob/master/backend/initialize.php): migration boot · Installation, initialization, and compatibility upgrade paths for existing deployments. · `backend/initialize.php`
- [Broadcaster](https://github.com/iqb-berlin/testcenter/tree/master/broadcaster): NestJS realtime · Websocket service distributing live session and monitoring events. · `broadcaster`
- [Websocket Gateway](https://github.com/iqb-berlin/testcenter/blob/master/broadcaster/src/common/websocket.gateway.ts): ws transport · Gateway layer for realtime client connections and event delivery. · `broadcaster/src/common/websocket.gateway.ts`
- [Session Realtime](https://github.com/iqb-berlin/testcenter/tree/master/broadcaster/src/test-session): test-session live · Runtime session state handling for test sessions, testees, and monitor updates. · `broadcaster/src/test-session`
- [Command API](https://github.com/iqb-berlin/testcenter/tree/master/broadcaster/src/command): control channel · Command and control endpoints used to drive realtime session actions. · `broadcaster/src/command`
- [File Server](https://github.com/iqb-berlin/testcenter/tree/master/file-server): Nginx/Lua · Protected binary and attachment delivery with auth and cache/Redis hooks. · `file-server`
- [Auth Hooks](https://github.com/iqb-berlin/testcenter/tree/master/file-server/auth): nginx lua · Authorization and cache logic for controlled file access. · `file-server/auth`

### Shared Contracts

Schemas, interfaces, and content definitions reused across runtimes.

- [Contracts](https://github.com/iqb-berlin/testcenter/tree/master/common): shared types · Shared TypeScript interfaces used by frontend and broadcaster. · `common`
- [Definitions](https://github.com/iqb-berlin/testcenter/tree/master/definitions): XML schemas · Schema-driven domain definitions for booklets, units, testtakers, browsers, and modes. · `definitions`

### Operations

Deployment, migration, documentation, and environment tooling.

- [Deployment](https://github.com/iqb-berlin/testcenter/tree/master/scripts/helm/testcenter): compose/helm · Docker Compose, Helm charts, Traefik, cache, and storage deployment assets. · `scripts/helm/testcenter`
- [DB Migrations](https://github.com/iqb-berlin/testcenter/tree/master/scripts/database): sql patches · Versioned schema patches and base database creation scripts. · `scripts/database`
- [Docs](https://github.com/iqb-berlin/testcenter/tree/master/docs): spec/docs · API specifications, installation guides, and operational documentation. · `docs`

### Verification

Automated tests and fixtures spanning the stack.

- [E2E Tests](https://github.com/iqb-berlin/testcenter/tree/master/e2e): cypress · System-level browser tests covering major user workflows and modes. · `e2e`
- [Backend Tests](https://github.com/iqb-berlin/testcenter/tree/master/backend/test): phpunit · Unit and initialization tests for API, DAO, files, and upgrade behavior. · `backend/test`
- [Sample Data](https://github.com/iqb-berlin/testcenter/tree/master/sampledata): fixtures · XML, JSON, and resource fixtures used for examples, testing, and system verification. · `sampledata`

## Connections

- Frontend → Backend API: API calls · The SPA authenticates and performs workspace and domain actions through the PHP API.
- Frontend → Broadcaster: websockets · The SPA connects to realtime channels for live session and monitoring updates.
- Frontend → File Server: downloads/uploads · The browser accesses protected binary resources through the dedicated file layer.
- Frontend → Shared UI: uses · Feature modules reuse shared components, services, interceptors, and utilities.
- Frontend → Contracts: types · Client-side code shares interface contracts with the realtime service.
- Test Control → Shared UI: reuses · Test execution relies on shared shell, dialog, and websocket infrastructure.
- Group Monitor → Broadcaster: monitors · Group monitoring consumes realtime session state and command feedback.
- Workspace Admin → Backend API: manages · Workspace administration uses the backend for tests, results, sys-check artifacts, and files.
- Superadmin → Backend API: administers · Superadmin workflows manage global users, workspaces, and configuration through the API.
- Sys Check → Backend API: reports · System check flow submits diagnostics and report data to the backend.
- Backend API → API Routes: routes · The backend entrypoint dispatches requests through the route table.
- API Routes → Domain Logic: dispatches · Routes land in controllers, DAOs, middleware, helpers, and workspace services.
- Backend API → Init & Upgrade: boots/upgrades · Startup and install scripts prepare or migrate persisted state.
- Backend API → DB Migrations: schema updates · Database evolution is managed as an explicit versioned patch stream.
- Broadcaster → Websocket Gateway: exposes · The realtime service exposes websocket endpoints through its gateway.
- Websocket Gateway → Session Realtime: dispatches events · Gateway traffic is routed into session, testee, and monitor modules.
- Session Realtime → Command API: control flow · Live session state can be influenced by command-oriented operations.
- Broadcaster → Backend API: runtime state · Realtime updates reflect backend-authorized session and test state.
- File Server → Auth Hooks: authenticates · Nginx relies on Lua auth hooks and cache integration before serving content.
- Deployment → Frontend: deploys · Charts and compose files package the frontend service for release.
- Deployment → Backend API: deploys · Deployment manifests include the PHP API service and its config/state volumes.
- Deployment → Broadcaster: deploys · The realtime broadcaster is part of the orchestrated stack.
- Deployment → File Server: deploys · The protected file service is deployed as a separate component.
- Deployment → DB Migrations: provisions · The operational tooling includes database setup and migration support.
- Docs → Backend API: specifies · API documentation describes backend endpoints and domain behavior.
- Docs → Frontend: guides · Product and installation docs support the UI workflows and deployment.
- E2E Tests → Frontend: drives · Cypress tests exercise the browser workflows end to end.
- E2E Tests → Backend API: integrates · System tests run against the backend API and data flow.
- E2E Tests → Broadcaster: validates · Realtime scenarios verify websocket-driven monitoring and session updates.
- Backend Tests → Backend API: verifies · PHPUnit coverage targets controllers, DAOs, files, and initialization.
- Backend Tests → DB Migrations: checks upgrades · Initialization tests validate schema patching and legacy-version handling.
- Sample Data → Definitions: conforms to · Fixtures implement the schema-driven content model used by the platform.
- Sample Data → E2E Tests: feeds · System test fixtures power realistic end-to-end scenarios.
