How iqb-berlin/testcenter works
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 Backend API · frontend Frontend · broadcaster Broadcaster · testcenter Deployment
Components 25
Client UI
Browser-facing Angular application and its feature areas.
- Frontend · Main browser application coordinating login, roles, and live workflows.
frontend - Test Control · Participant-facing test execution, navigation, and review logic.
frontend/src/app/test-controller - Group Monitor · Supervisor view for monitoring test sessions and applying controls.
frontend/src/app/group-monitor - Workspace Admin · Workspace-scoped management for tests, files, results, and sys-check data.
frontend/src/app/workspace-admin - Superadmin · Global administration for users, workspaces, and settings.
frontend/src/app/superadmin - Sys Check · Client-side system check, questionnaire, network test, and report flow.
frontend/src/app/sys-check - Shared UI · 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 · HTTP API entrypoint for authentication, persistence, workspace actions, and initialization.
backend - API Routes · Top-level request routing and bootstrap for backend endpoints.
backend/routes.php - Domain Logic · Controllers, data access, middleware, helpers, and workspace report logic.
backend/src - Init & Upgrade · Installation, initialization, and compatibility upgrade paths for existing deployments.
backend/initialize.php - Broadcaster · Websocket service distributing live session and monitoring events.
broadcaster - Websocket Gateway · Gateway layer for realtime client connections and event delivery.
broadcaster/src/common/websocket.gateway.ts - Session Realtime · Runtime session state handling for test sessions, testees, and monitor updates.
broadcaster/src/test-session - Command API · Command and control endpoints used to drive realtime session actions.
broadcaster/src/command - File Server · Protected binary and attachment delivery with auth and cache/Redis hooks.
file-server - Auth Hooks · Authorization and cache logic for controlled file access.
file-server/auth
Shared Contracts
Schemas, interfaces, and content definitions reused across runtimes.
- Contracts · Shared TypeScript interfaces used by frontend and broadcaster.
common - Definitions · Schema-driven domain definitions for booklets, units, testtakers, browsers, and modes.
definitions
Operations
Deployment, migration, documentation, and environment tooling.
- Deployment · Docker Compose, Helm charts, Traefik, cache, and storage deployment assets.
scripts/helm/testcenter - DB Migrations · Versioned schema patches and base database creation scripts.
scripts/database - Docs · API specifications, installation guides, and operational documentation.
docs
Verification
Automated tests and fixtures spanning the stack.
- E2E Tests · System-level browser tests covering major user workflows and modes.
e2e - Backend Tests · Unit and initialization tests for API, DAO, files, and upgrade behavior.
backend/test - Sample Data · XML, JSON, and resource fixtures used for examples, testing, and system verification.
sampledata
Connections 33
- 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.