# 1iekki/cempu architecture

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

- Interactive diagram: https://gitdiagram.com/1iekki/cempu
- Repository: https://github.com/1iekki/cempu

## Overview

CEMPU measures classroom engagement from microphone audio and presents group results in a dashboard. The principal workflow is: a device records audio, computes a live volume-based engagement measure, and uploads recordings; the backend accepts recordings and exposes analysis and device-control endpoints; analysis transcribes speech, derives semantic context features, diarizes speakers, and classifies on-topic discussion; results and live measurements are surfaced to the dashboard. MQTT carries device commands and measurements, while WebSockets relay device messages. Several dashboard-to-backend details and unsampled analysis internals are not shown, so those links are marked unverified or omitted.

Main entry points: [`backend/main.py`](https://github.com/1iekki/cempu/blob/main/backend/main.py) (HTTP and WebSocket API), [`client/main.py`](https://github.com/1iekki/cempu/blob/main/client/main.py) (Raspberry Pi), [`dashboard/src/routes/group/[id]/+page.svelte`](https://github.com/1iekki/cempu/blob/main/dashboard/src/routes/group/%5Bid%5D/%2Bpage.svelte) (Group results), [`backend/cempuMQTT.py`](https://github.com/1iekki/cempu/blob/main/backend/cempuMQTT.py) (MQTT bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Device capture"]
  node_raspberry["Raspberry Pi<br/>[main.py]"]
  node_volume["Volume measure<br/>[volumeAnalysis.py]"]
  node_device_mqtt["Device MQTT<br/>[cempuMQTT.py]"]
end

subgraph group_server["Backend services"]
  node_backend_api["HTTP and WebSocket API<br/>[main.py]"]
  node_mqtt_bridge["MQTT bridge<br/>[cempuMQTT.py]"]
  node_connections["WebSocket connections"]
  node_recordings[("Audio recordings<br/>[analysisParams.py]")]
end

subgraph group_analysis["Audio analysis"]
  node_analysis_config["Analysis configuration<br/>[analysisParams.py]"]
  node_context_processing["Context processing"]
  node_transcription["Speech transcription<br/>[transcriber.py]"]
  node_semantic_search["Semantic search<br/>[semanticSearch.py]"]
  node_speaker_diarization["Speaker diarization"]
  node_context_classifier["On-topic classifier"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_home["Dashboard overview<br/>[+page.svelte]"]
  node_group_view["Group results<br/>[+page.svelte]"]
  node_group_store["Group state<br/>[groupStore.ts]"]
  node_analysis_store["Analysis state<br/>[analysisStore.ts]"]
  node_group_info["Group information<br/>[groupInfo.svelte]"]
end

node_instructor(("Instructor"))
node_broker(("MQTT broker"))

node_instructor -->|"controls recording"| node_raspberry
node_raspberry -->|"measures audio"| node_volume
node_raspberry -->|"sends engagement"| node_device_mqtt
node_raspberry -->|"uploads audio"| node_backend_api
node_device_mqtt -.->|"publishes and subscribes"| node_broker
node_backend_api -->|"writes uploads"| node_recordings
node_backend_api -->|"uses settings"| node_analysis_config
node_backend_api -->|"runs analysis"| node_context_processing
node_backend_api -->|"runs analysis"| node_speaker_diarization
node_backend_api -->|"scores analysis"| node_context_classifier
node_backend_api -->|"routes device messages"| node_mqtt_bridge
node_mqtt_bridge -->|"broadcasts messages"| node_connections
node_mqtt_bridge -.->|"exchanges MQTT messages"| node_broker
node_backend_api -->|"manages WebSockets"| node_connections
node_context_processing -->|"transcribes audio"| node_transcription
node_context_processing -->|"encodes and compares"| node_semantic_search
node_backend_api -.->|"serves results"| node_dashboard_home
node_backend_api -.->|"serves group data"| node_group_view
node_dashboard_home -.->|"uses group state"| node_group_store
node_group_view -.->|"uses group state"| node_group_store
node_group_view -.->|"uses analysis state"| node_analysis_store
node_group_view -.->|"renders details"| node_group_info

click node_raspberry "https://github.com/1iekki/cempu/blob/main/client/main.py"
click node_volume "https://github.com/1iekki/cempu/blob/main/client/volumeAnalysis.py"
click node_device_mqtt "https://github.com/1iekki/cempu/blob/main/client/cempuMQTT.py"
click node_backend_api "https://github.com/1iekki/cempu/blob/main/backend/main.py"
click node_mqtt_bridge "https://github.com/1iekki/cempu/blob/main/backend/cempuMQTT.py"
click node_connections "https://github.com/1iekki/cempu/blob/main/backend/connectionManager.py"
click node_analysis_config "https://github.com/1iekki/cempu/blob/main/backend/analysisParams.py"
click node_context_processing "https://github.com/1iekki/cempu/blob/main/backend/contextProcessor.py"
click node_transcription "https://github.com/1iekki/cempu/blob/main/backend/transcriber.py"
click node_semantic_search "https://github.com/1iekki/cempu/blob/main/backend/semanticSearch.py"
click node_speaker_diarization "https://github.com/1iekki/cempu/blob/main/backend/speakerDiarization.py"
click node_context_classifier "https://github.com/1iekki/cempu/blob/main/backend/contextClassifier.py"
click node_recordings "https://github.com/1iekki/cempu/blob/main/backend/analysisParams.py"
click node_dashboard_home "https://github.com/1iekki/cempu/blob/main/dashboard/src/routes/%2Bpage.svelte"
click node_group_view "https://github.com/1iekki/cempu/blob/main/dashboard/src/routes/group/%5Bid%5D/%2Bpage.svelte"
click node_group_store "https://github.com/1iekki/cempu/blob/main/dashboard/src/lib/stores/groupStore.ts"
click node_analysis_store "https://github.com/1iekki/cempu/blob/main/dashboard/src/lib/stores/analysisStore.ts"
click node_group_info "https://github.com/1iekki/cempu/blob/main/dashboard/src/lib/components/groupInfo/groupInfo.svelte"

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_raspberry,node_volume,node_device_mqtt toneBlue
class node_backend_api,node_mqtt_bridge,node_connections,node_recordings toneAmber
class node_analysis_config,node_context_processing,node_transcription,node_semantic_search,node_speaker_diarization,node_context_classifier toneMint
class node_dashboard_home,node_group_view,node_group_store,node_analysis_store,node_group_info toneRose
class node_instructor,node_broker toneIndigo
```

## Components

### Device capture

- [Raspberry Pi](https://github.com/1iekki/cempu/blob/main/client/main.py): `client/main.py`
- [Volume measure](https://github.com/1iekki/cempu/blob/main/client/volumeAnalysis.py): `client/volumeAnalysis.py`
- [Device MQTT](https://github.com/1iekki/cempu/blob/main/client/cempuMQTT.py): `client/cempuMQTT.py`

### Backend services

- [HTTP and WebSocket API](https://github.com/1iekki/cempu/blob/main/backend/main.py): `backend/main.py`
- [MQTT bridge](https://github.com/1iekki/cempu/blob/main/backend/cempuMQTT.py): `backend/cempuMQTT.py`
- [WebSocket connections](https://github.com/1iekki/cempu/blob/main/backend/connectionManager.py): `backend/connectionManager.py`
- [Audio recordings](https://github.com/1iekki/cempu/blob/main/backend/analysisParams.py): `backend/analysisParams.py`

### Audio analysis

- [Analysis configuration](https://github.com/1iekki/cempu/blob/main/backend/analysisParams.py): `backend/analysisParams.py`
- [Context processing](https://github.com/1iekki/cempu/blob/main/backend/contextProcessor.py): `backend/contextProcessor.py`
- [Speech transcription](https://github.com/1iekki/cempu/blob/main/backend/transcriber.py): `backend/transcriber.py`
- [Semantic search](https://github.com/1iekki/cempu/blob/main/backend/semanticSearch.py): `backend/semanticSearch.py`
- [Speaker diarization](https://github.com/1iekki/cempu/blob/main/backend/speakerDiarization.py): `backend/speakerDiarization.py`
- [On-topic classifier](https://github.com/1iekki/cempu/blob/main/backend/contextClassifier.py): `backend/contextClassifier.py`

### Dashboard

- [Dashboard overview](https://github.com/1iekki/cempu/blob/main/dashboard/src/routes/%2Bpage.svelte): `dashboard/src/routes/+page.svelte`
- [Group results](https://github.com/1iekki/cempu/blob/main/dashboard/src/routes/group/%5Bid%5D/%2Bpage.svelte): `dashboard/src/routes/group/[id]/+page.svelte`
- [Group state](https://github.com/1iekki/cempu/blob/main/dashboard/src/lib/stores/groupStore.ts): `dashboard/src/lib/stores/groupStore.ts`
- [Analysis state](https://github.com/1iekki/cempu/blob/main/dashboard/src/lib/stores/analysisStore.ts): `dashboard/src/lib/stores/analysisStore.ts`
- [Group information](https://github.com/1iekki/cempu/blob/main/dashboard/src/lib/components/groupInfo/groupInfo.svelte): `dashboard/src/lib/components/groupInfo/groupInfo.svelte`

### Other components

- **Instructor**
- **MQTT broker**

## Connections

- Instructor → Raspberry Pi: controls recording (evidence: `client/main.py`)
- Raspberry Pi → Volume measure: measures audio (evidence: `client/main.py`)
- Raspberry Pi → Device MQTT: sends engagement (evidence: `client/main.py`)
- Raspberry Pi → HTTP and WebSocket API: uploads audio (evidence: `client/main.py`)
- Device MQTT → MQTT broker: publishes and subscribes
- HTTP and WebSocket API → Audio recordings: writes uploads (evidence: `backend/main.py`)
- HTTP and WebSocket API → Analysis configuration: uses settings (evidence: `backend/main.py`)
- HTTP and WebSocket API → Context processing: runs analysis (evidence: `backend/main.py`)
- HTTP and WebSocket API → Speaker diarization: runs analysis (evidence: `backend/main.py`)
- HTTP and WebSocket API → On-topic classifier: scores analysis (evidence: `backend/main.py`)
- HTTP and WebSocket API → MQTT bridge: routes device messages (evidence: `backend/main.py`)
- MQTT bridge → WebSocket connections: broadcasts messages (evidence: `backend/cempuMQTT.py`)
- MQTT bridge → MQTT broker: exchanges MQTT messages
- HTTP and WebSocket API → WebSocket connections: manages WebSockets (evidence: `backend/main.py`)
- Context processing → Speech transcription: transcribes audio (evidence: `backend/contextProcessor.py`)
- Context processing → Semantic search: encodes and compares (evidence: `backend/contextProcessor.py`)
- HTTP and WebSocket API → Dashboard overview: serves results
- HTTP and WebSocket API → Group results: serves group data
- Dashboard overview → Group state: uses group state
- Group results → Group state: uses group state
- Group results → Analysis state: uses analysis state
- Group results → Group information: renders details
