# legendop4/spemcs architecture

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

- Interactive diagram: https://gitdiagram.com/legendop4/spemcs
- Repository: https://github.com/legendop4/spemcs

## Overview

SPEMCS centrally manages secure, proctored exams across Windows lab workstations. Operators use the web console to manage devices, policies, and exams; the backend enrolls endpoints, compiles and signs policies, distributes them over authenticated WebSockets, and gates activation on enforcement readiness. The endpoint service verifies policy and applies firewall controls while monitoring processes and network activity, then uploads telemetry. The README documents this end-to-end workflow and the dashboard’s major capabilities; source excerpts and the index support several internal links, but not every route or runtime integration was sampled.

Main entry points: [`Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs`](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs) (Privileged agent service), [`backend/backend/app/main.py`](https://github.com/legendop4/spemcs/blob/main/backend/backend/app/main.py) (Backend API), [`backend/backend/websocket/agent_ws.py`](https://github.com/legendop4/spemcs/blob/main/backend/backend/websocket/agent_ws.py) (Agent WebSocket), [`Endpoint-agent/src/Spemcs.Agent.Core/EventUploaderWorker.cs`](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/EventUploaderWorker.cs) (Telemetry uploader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Operator console"]
  node_dashboard["Management dashboard<br/>[App.tsx]"]
  node_exam_ui["Exam management<br/>[ExamShieldPage.tsx]"]
  node_api_client["Dashboard API client<br/>[api.ts]"]
end

subgraph group_backend["Backend control plane"]
  node_api["Backend API<br/>[main.py]"]
  node_agent_routes["Agent endpoints<br/>[agent_api.py]"]
  node_policy_services["Policy compilation<br/>[policy_compiler.py]"]
  node_policy_signing["Policy signing"]
  node_readiness["Activation readiness"]
  node_exam_service["Exam lifecycle<br/>[exam_service.py]"]
end

subgraph group_realtime["Realtime and persistence"]
  node_agent_ws["Agent WebSocket<br/>[agent_ws.py]"]
  node_ws_manager["Connection manager<br/>[manager.py]"]
  node_database[("Relational database<br/>[database.py]")]
  node_device_model["Device records<br/>[device.py]"]
end

subgraph group_agent["Endpoint agent"]
  node_service["Privileged agent service<br/>[AgentWorker.cs]"]
  node_central_socket["Central WebSocket client"]
  node_policy_receiver["Policy verification<br/>[PolicyReceiver.cs]"]
  node_monitoring["Process monitoring<br/>[Monitoring.cs]"]
  node_network_collector["Network telemetry"]
  node_event_uploader["Telemetry uploader"]
  node_agent_store[("Local agent store")]
end

subgraph group_enforcement["Policy enforcement"]
  node_state_machine["Enforcement state machine"]
  node_firewall["Windows firewall"]
end

node_operator(("Exam operator"))
node_endpoint(("Windows workstation"))

node_operator -->|"manages exams"| node_dashboard
node_dashboard -->|"routes to"| node_exam_ui
node_exam_ui -.->|"requests operations"| node_api_client
node_api_client -.->|"calls API"| node_api
node_endpoint -->|"enrolls"| node_agent_routes
node_agent_routes -.->|"persists records"| node_database
node_api -.->|"routes policy operations"| node_policy_services
node_policy_services -.->|"signs policy"| node_policy_signing
node_api -.->|"manages exams"| node_exam_service
node_exam_service -->|"checks readiness"| node_readiness
node_readiness -->|"checks presence"| node_ws_manager
node_policy_signing -->|"distributes signed policy"| node_agent_ws
node_agent_ws -->|"registers connections"| node_ws_manager
node_agent_ws -->|"reads device state"| node_database
node_database -->|"stores device records"| node_device_model
node_service -->|"hosts worker"| node_central_socket
node_central_socket -->|"validates policy"| node_policy_receiver
node_policy_receiver -->|"verified policy"| node_state_machine
node_state_machine -->|"enforces rules"| node_firewall
node_endpoint -->|"runs monitoring"| node_monitoring
node_endpoint -->|"audits connections"| node_network_collector
node_service -->|"coordinates monitoring"| node_monitoring
node_service -->|"coordinates collection"| node_network_collector
node_service -->|"starts uploader"| node_event_uploader
node_event_uploader -->|"reads queued events"| node_agent_store
node_event_uploader -.->|"uploads telemetry"| node_agent_ws
node_api -.->|"serves management data"| node_dashboard

click node_dashboard "https://github.com/legendop4/spemcs/blob/main/frontend/src/App.tsx"
click node_exam_ui "https://github.com/legendop4/spemcs/blob/main/frontend/src/pages/ExamShieldPage.tsx"
click node_api_client "https://github.com/legendop4/spemcs/blob/main/frontend/src/services/api.ts"
click node_api "https://github.com/legendop4/spemcs/blob/main/backend/backend/app/main.py"
click node_agent_routes "https://github.com/legendop4/spemcs/blob/main/backend/backend/routes/agent_api.py"
click node_policy_services "https://github.com/legendop4/spemcs/blob/main/backend/backend/services/policy_compiler.py"
click node_policy_signing "https://github.com/legendop4/spemcs/blob/main/backend/backend/services/signing_key_manager.py"
click node_readiness "https://github.com/legendop4/spemcs/blob/main/backend/backend/services/enforcement_readiness.py"
click node_exam_service "https://github.com/legendop4/spemcs/blob/main/backend/backend/services/exam_service.py"
click node_agent_ws "https://github.com/legendop4/spemcs/blob/main/backend/backend/websocket/agent_ws.py"
click node_ws_manager "https://github.com/legendop4/spemcs/blob/main/backend/backend/websocket/manager.py"
click node_database "https://github.com/legendop4/spemcs/blob/main/backend/backend/app/database.py"
click node_device_model "https://github.com/legendop4/spemcs/blob/main/backend/backend/models/device.py"
click node_service "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs"
click node_central_socket "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Service/CentralWebSocketWorker.cs"
click node_policy_receiver "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/Network/PolicyReceiver.cs"
click node_monitoring "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/Monitoring.cs"
click node_network_collector "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/NetworkCollector.cs"
click node_event_uploader "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/EventUploaderWorker.cs"
click node_state_machine "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/Network/EnforcementStateMachine.cs"
click node_firewall "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/Network/WindowsFirewallAdapter.cs"
click node_agent_store "https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/SqliteAgentStore.cs"

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_dashboard,node_exam_ui,node_api_client toneBlue
class node_api,node_agent_routes,node_policy_services,node_policy_signing,node_readiness,node_exam_service toneAmber
class node_agent_ws,node_ws_manager,node_database,node_device_model toneMint
class node_service,node_central_socket,node_policy_receiver,node_monitoring,node_network_collector,node_event_uploader,node_agent_store toneRose
class node_state_machine,node_firewall,node_operator,node_endpoint toneIndigo
```

## Components

### Operator console

- [Management dashboard](https://github.com/legendop4/spemcs/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Exam management](https://github.com/legendop4/spemcs/blob/main/frontend/src/pages/ExamShieldPage.tsx): `frontend/src/pages/ExamShieldPage.tsx`
- [Dashboard API client](https://github.com/legendop4/spemcs/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Backend control plane

- [Backend API](https://github.com/legendop4/spemcs/blob/main/backend/backend/app/main.py): `backend/backend/app/main.py`
- [Agent endpoints](https://github.com/legendop4/spemcs/blob/main/backend/backend/routes/agent_api.py): `backend/backend/routes/agent_api.py`
- [Policy compilation](https://github.com/legendop4/spemcs/blob/main/backend/backend/services/policy_compiler.py): `backend/backend/services/policy_compiler.py`
- [Policy signing](https://github.com/legendop4/spemcs/blob/main/backend/backend/services/signing_key_manager.py): `backend/backend/services/signing_key_manager.py`
- [Activation readiness](https://github.com/legendop4/spemcs/blob/main/backend/backend/services/enforcement_readiness.py): `backend/backend/services/enforcement_readiness.py`
- [Exam lifecycle](https://github.com/legendop4/spemcs/blob/main/backend/backend/services/exam_service.py): `backend/backend/services/exam_service.py`

### Realtime and persistence

- [Agent WebSocket](https://github.com/legendop4/spemcs/blob/main/backend/backend/websocket/agent_ws.py): `backend/backend/websocket/agent_ws.py`
- [Connection manager](https://github.com/legendop4/spemcs/blob/main/backend/backend/websocket/manager.py): `backend/backend/websocket/manager.py`
- [Relational database](https://github.com/legendop4/spemcs/blob/main/backend/backend/app/database.py): `backend/backend/app/database.py`
- [Device records](https://github.com/legendop4/spemcs/blob/main/backend/backend/models/device.py): `backend/backend/models/device.py`

### Endpoint agent

- [Privileged agent service](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs): `Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs`
- [Central WebSocket client](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Service/CentralWebSocketWorker.cs): `Endpoint-agent/src/Spemcs.Agent.Service/CentralWebSocketWorker.cs`
- [Policy verification](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/Network/PolicyReceiver.cs): `Endpoint-agent/src/Spemcs.Agent.Core/Network/PolicyReceiver.cs`
- [Process monitoring](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/Monitoring.cs): `Endpoint-agent/src/Spemcs.Agent.Core/Monitoring.cs`
- [Network telemetry](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/NetworkCollector.cs): `Endpoint-agent/src/Spemcs.Agent.Core/NetworkCollector.cs`
- [Telemetry uploader](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/EventUploaderWorker.cs): `Endpoint-agent/src/Spemcs.Agent.Core/EventUploaderWorker.cs`
- [Local agent store](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/SqliteAgentStore.cs): `Endpoint-agent/src/Spemcs.Agent.Core/SqliteAgentStore.cs`

### Policy enforcement

- [Enforcement state machine](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/Network/EnforcementStateMachine.cs): `Endpoint-agent/src/Spemcs.Agent.Core/Network/EnforcementStateMachine.cs`
- [Windows firewall](https://github.com/legendop4/spemcs/blob/main/Endpoint-agent/src/Spemcs.Agent.Core/Network/WindowsFirewallAdapter.cs): `Endpoint-agent/src/Spemcs.Agent.Core/Network/WindowsFirewallAdapter.cs`

### Other components

- **Exam operator**
- **Windows workstation**

## Connections

- Exam operator → Management dashboard: manages exams
- Management dashboard → Exam management: routes to (evidence: `frontend/src/App.tsx`)
- Exam management → Dashboard API client: requests operations
- Dashboard API client → Backend API: calls API
- Windows workstation → Agent endpoints: enrolls
- Agent endpoints → Relational database: persists records
- Backend API → Policy compilation: routes policy operations
- Policy compilation → Policy signing: signs policy
- Backend API → Exam lifecycle: manages exams
- Exam lifecycle → Activation readiness: checks readiness
- Activation readiness → Connection manager: checks presence
- Policy signing → Agent WebSocket: distributes signed policy
- Agent WebSocket → Connection manager: registers connections (evidence: `backend/backend/websocket/agent_ws.py`)
- Agent WebSocket → Relational database: reads device state (evidence: `backend/backend/websocket/agent_ws.py`)
- Relational database → Device records: stores device records (evidence: `backend/backend/models/device.py`)
- Privileged agent service → Central WebSocket client: hosts worker (evidence: `Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs`)
- Central WebSocket client → Policy verification: validates policy (evidence: `Endpoint-agent/src/Spemcs.Agent.Service/CentralWebSocketWorker.cs`)
- Policy verification → Enforcement state machine: verified policy
- Enforcement state machine → Windows firewall: enforces rules (evidence: `Endpoint-agent/src/Spemcs.Agent.Core/Network/EnforcementStateMachine.cs`)
- Windows workstation → Process monitoring: runs monitoring
- Windows workstation → Network telemetry: audits connections
- Privileged agent service → Process monitoring: coordinates monitoring (evidence: `Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs`)
- Privileged agent service → Network telemetry: coordinates collection (evidence: `Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs`)
- Privileged agent service → Telemetry uploader: starts uploader (evidence: `Endpoint-agent/src/Spemcs.Agent.Service/AgentWorker.cs`)
- Telemetry uploader → Local agent store: reads queued events (evidence: `Endpoint-agent/src/Spemcs.Agent.Core/EventUploaderWorker.cs`)
- Telemetry uploader → Agent WebSocket: uploads telemetry
- Backend API → Management dashboard: serves management data
