# plaksych/edu-attendance-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/plaksych/edu-attendance-tracker
- Repository: https://github.com/plaksych/edu-attendance-tracker
- Video tour (about a minute): https://gitdiagram.com/plaksych/edu-attendance-tracker/video

## Overview

Edu Attendance Tracker schedules classes, accepts media uploads, and—when the camera workflow is enabled—records RTSP clips for recognition. Backend APIs and workers use PostgreSQL for domain data and job queues, while MinIO stores original and annotated media. The frontend presents schedule, sessions, recognition, catalogs, and attendance analytics. The README documents separate capture and recognition workers and a static demo mode; sampled source confirms API startup, frontend routing/API selection, storage helpers, and worker processing, but not every backend route or worker handoff.

Main entry points: [`backend/app/main.py`](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/main.py) (REST API), [`backend/app/core/database.py`](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/core/database.py) (PostgreSQL), [`backend/app/api/v1/recognition.py`](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/recognition.py) (Recognition routes), [`backend/app/core/object_storage.py`](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/core/object_storage.py) (MinIO media store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_app["Page router<br/>[App.tsx]"]
  node_pages["Product pages"]
  node_api_client["API client<br/>[client.ts]"]
  node_static_client["Demo data API<br/>[staticClient.ts]"]
end

subgraph group_backend["Backend services"]
  node_api_server["REST API<br/>[main.py]"]
  node_schedule_api["Schedule routes<br/>[schedule.py]"]
  node_session_api["Session routes<br/>[sessions.py]"]
  node_recognition_api["Recognition routes<br/>[recognition.py]"]
  node_catalog_api["Catalog routes<br/>[catalog.py]"]
  node_stats_api["Statistics routes<br/>[stats.py]"]
  node_scheduler["Measurement scheduler<br/>[scheduler.py]"]
  node_aggregation["Attendance aggregation<br/>[aggregation.py]"]
  node_imports["Timetable import"]
  node_sessions["Session service<br/>[sessions.py]"]
end

subgraph group_capture["Capture worker"]
  node_capture_worker["Capture manager<br/>[main.py]"]
end

subgraph group_recognition["Recognition worker"]
  node_rec_worker["Recognition worker<br/>[main.py]"]
  node_processor["Job processor<br/>[processor.py]"]
  node_detector["Person detector<br/>[detector.py]"]
end

subgraph group_infra["Shared storage"]
  node_postgres[("PostgreSQL<br/>[database.py]")]
  node_minio[("MinIO media store<br/>[object_storage.py]")]
end

node_operator(("Staff user"))
node_rtsp(("RTSP cameras"))
node_media_upload(("Uploaded media"))

node_operator -->|"uses"| node_app
node_app -->|"routes to"| node_pages
node_pages -->|"requests data"| node_api_client
node_api_client -->|"REST requests"| node_api_server
node_api_client -.->|"selects demo mode"| node_static_client
node_static_client -.->|"returns demo data"| node_pages
node_api_server -->|"dispatches"| node_schedule_api
node_api_server -->|"dispatches"| node_session_api
node_api_server -->|"dispatches"| node_recognition_api
node_api_server -->|"dispatches"| node_catalog_api
node_api_server -->|"dispatches"| node_stats_api
node_api_server -->|"starts"| node_scheduler
node_api_server -->|"initializes bucket"| node_minio
node_schedule_api -->|"imports timetable"| node_imports
node_schedule_api -->|"reads/writes schedule"| node_postgres
node_session_api -->|"delegates"| node_sessions
node_sessions -->|"reads/writes sessions"| node_postgres
node_scheduler -->|"creates sessions and jobs"| node_postgres
node_aggregation -->|"reads results"| node_postgres
node_recognition_api -->|"queues uploads"| node_postgres
node_recognition_api -->|"signs media URLs"| node_minio
node_stats_api -->|"reads attendance data"| node_postgres
node_capture_worker -->|"claims and updates tasks"| node_postgres
node_capture_worker -.->|"records streams"| node_rtsp
node_capture_worker -->|"uploads recordings"| node_minio
node_rec_worker -->|"claims and completes jobs"| node_postgres
node_rec_worker -->|"processes job"| node_processor
node_processor -->|"downloads and uploads media"| node_minio
node_processor -->|"detects people"| node_detector
node_media_upload -->|"uploads files"| node_recognition_api
node_api_server -->|"combines measurement results"| node_aggregation

click node_app "https://github.com/plaksych/edu-attendance-tracker/blob/main/frontend/src/App.tsx"
click node_pages "https://github.com/plaksych/edu-attendance-tracker/tree/main/frontend/src/pages"
click node_api_client "https://github.com/plaksych/edu-attendance-tracker/blob/main/frontend/src/api/client.ts"
click node_static_client "https://github.com/plaksych/edu-attendance-tracker/blob/main/frontend/src/api/staticClient.ts"
click node_api_server "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/main.py"
click node_schedule_api "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/schedule.py"
click node_session_api "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/sessions.py"
click node_recognition_api "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/recognition.py"
click node_catalog_api "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/catalog.py"
click node_stats_api "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/stats.py"
click node_scheduler "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/services/scheduler.py"
click node_aggregation "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/services/aggregation.py"
click node_imports "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/services/timetable_import.py"
click node_sessions "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/services/sessions.py"
click node_capture_worker "https://github.com/plaksych/edu-attendance-tracker/blob/main/capture/app/main.py"
click node_rec_worker "https://github.com/plaksych/edu-attendance-tracker/blob/main/recognition/app/main.py"
click node_processor "https://github.com/plaksych/edu-attendance-tracker/blob/main/recognition/app/processor.py"
click node_detector "https://github.com/plaksych/edu-attendance-tracker/blob/main/recognition/app/detector.py"
click node_postgres "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/core/database.py"
click node_minio "https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/core/object_storage.py"

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_app,node_pages,node_api_client,node_static_client,node_operator toneBlue
class node_api_server,node_schedule_api,node_session_api,node_recognition_api,node_catalog_api,node_stats_api,node_scheduler,node_aggregation,node_imports,node_sessions toneAmber
class node_capture_worker toneMint
class node_rec_worker,node_processor,node_detector toneRose
class node_postgres,node_minio,node_rtsp,node_media_upload toneIndigo
```

## Components

### Web application

- [Page router](https://github.com/plaksych/edu-attendance-tracker/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Product pages](https://github.com/plaksych/edu-attendance-tracker/tree/main/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/plaksych/edu-attendance-tracker/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Demo data API](https://github.com/plaksych/edu-attendance-tracker/blob/main/frontend/src/api/staticClient.ts): `frontend/src/api/staticClient.ts`

### Backend services

- [REST API](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/main.py): `backend/app/main.py`
- [Schedule routes](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/schedule.py): `backend/app/api/v1/schedule.py`
- [Session routes](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/sessions.py): `backend/app/api/v1/sessions.py`
- [Recognition routes](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/recognition.py): `backend/app/api/v1/recognition.py`
- [Catalog routes](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/catalog.py): `backend/app/api/v1/catalog.py`
- [Statistics routes](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/api/v1/stats.py): `backend/app/api/v1/stats.py`
- [Measurement scheduler](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/services/scheduler.py): `backend/app/services/scheduler.py`
- [Attendance aggregation](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/services/aggregation.py): `backend/app/services/aggregation.py`
- [Timetable import](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/services/timetable_import.py): `backend/app/services/timetable_import.py`
- [Session service](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/services/sessions.py): `backend/app/services/sessions.py`

### Capture worker

- [Capture manager](https://github.com/plaksych/edu-attendance-tracker/blob/main/capture/app/main.py): `capture/app/main.py`

### Recognition worker

- [Recognition worker](https://github.com/plaksych/edu-attendance-tracker/blob/main/recognition/app/main.py): `recognition/app/main.py`
- [Job processor](https://github.com/plaksych/edu-attendance-tracker/blob/main/recognition/app/processor.py): `recognition/app/processor.py`
- [Person detector](https://github.com/plaksych/edu-attendance-tracker/blob/main/recognition/app/detector.py): `recognition/app/detector.py`

### Shared storage

- [PostgreSQL](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [MinIO media store](https://github.com/plaksych/edu-attendance-tracker/blob/main/backend/app/core/object_storage.py): `backend/app/core/object_storage.py`

### Other components

- **Staff user**
- **RTSP cameras**
- **Uploaded media**

## Connections

- Staff user → Page router: uses
- Page router → Product pages: routes to
- Product pages → API client: requests data
- API client → REST API: REST requests
- API client → Demo data API: selects demo mode
- Demo data API → Product pages: returns demo data
- REST API → Schedule routes: dispatches
- REST API → Session routes: dispatches
- REST API → Recognition routes: dispatches
- REST API → Catalog routes: dispatches
- REST API → Statistics routes: dispatches
- REST API → Measurement scheduler: starts
- REST API → MinIO media store: initializes bucket
- Schedule routes → Timetable import: imports timetable
- Schedule routes → PostgreSQL: reads/writes schedule
- Session routes → Session service: delegates
- Session service → PostgreSQL: reads/writes sessions
- Measurement scheduler → PostgreSQL: creates sessions and jobs
- Attendance aggregation → PostgreSQL: reads results
- Recognition routes → PostgreSQL: queues uploads
- Recognition routes → MinIO media store: signs media URLs
- Statistics routes → PostgreSQL: reads attendance data
- Capture manager → PostgreSQL: claims and updates tasks
- Capture manager → RTSP cameras: records streams
- Capture manager → MinIO media store: uploads recordings
- Recognition worker → PostgreSQL: claims and completes jobs
- Recognition worker → Job processor: processes job
- Job processor → MinIO media store: downloads and uploads media
- Job processor → Person detector: detects people
- Uploaded media → Recognition routes: uploads files
- REST API → Attendance aggregation: combines measurement results