# ndktu/ndktu-student-face-platform architecture

> Architecture diagram of the GitHub repository ndktu/ndktu-student-face-platform, 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/ndktu/ndktu-student-face-platform
- Repository: https://github.com/ndktu/ndktu-student-face-platform

## Overview

This repository implements an educational platform: users sign in and reach role- and permission-aware dashboards, then manage courses, organization data, quizzes, files, and student services. A separate face-detection API supports video-based face checks. The sampled source confirms application routing, selected endpoint-to-repository calls, EduPlan authentication, file storage, and face-service startup; many other subsystem links are represented only at their documented/tree level, so uncertain internal wiring is omitted.

Main entry points: [`backend/app/modules/router.py`](https://github.com/ndktu/ndktu-student-face-platform/blob/main/backend/app/modules/router.py) (API router), [`backend/app/core/database`](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/core/database) (Platform database), [`face-detection/app/services/video_service.py`](https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/services/video_service.py) (Video analysis), [`frontend/src/App.tsx`](https://github.com/ndktu/ndktu-student-face-platform/blob/main/frontend/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
  node_webpages["Role-based pages"]
  node_webservices["API services"]
end

subgraph group_platform["Platform API"]
  node_backend["API application<br/>[main.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_auth["Identity and access"]
  node_org["Organization structure"]
  node_database[("Platform database")]
end

subgraph group_learning["Learning services"]
  node_courses["Course delivery"]
  node_quizzes["Assessment and quizzes"]
  node_psych["Psychology services"]
  node_announcements["Announcements"]
  node_files["File library"]
end

subgraph group_integrations["Integrations"]
  node_eduplan["EduPlan integration"]
  node_zoom["Zoom integration"]
end

subgraph group_vision["Face detection"]
  node_face_api["Face detection API<br/>[main.py]"]
  node_face_routes["Face endpoints"]
  node_video_service["Video analysis<br/>[video_service.py]"]
  node_face_models["Detection and recognition<br/>[face_detector.py]"]
  node_face_storage["Captured face storage<br/>[face_storage.py]"]
end

node_user(("Platform user"))
node_eduplan_service{{"EduPlan service"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"checks identity"| node_authui
node_webapp -->|"routes to"| node_webpages
node_webpages -->|"requests data"| node_webservices
node_webservices -->|"calls API"| node_backend
node_backend -->|"mounts routes"| node_api_router
node_api_router -->|"dispatches"| node_auth
node_api_router -->|"dispatches"| node_org
node_api_router -->|"dispatches"| node_courses
node_api_router -->|"dispatches"| node_quizzes
node_api_router -->|"dispatches"| node_psych
node_api_router -->|"dispatches"| node_announcements
node_api_router -->|"dispatches"| node_files
node_auth -->|"reads and writes"| node_database
node_org -->|"reads and writes"| node_database
node_courses -->|"reads and writes"| node_database
node_quizzes -->|"reads and writes"| node_database
node_psych -->|"reads and writes"| node_database
node_announcements -->|"reads and writes"| node_database
node_files -->|"records file metadata"| node_database
node_eduplan -.->|"authenticates with"| node_eduplan_service
node_api_router -->|"dispatches"| node_eduplan
node_api_router -->|"dispatches"| node_zoom
node_face_api -->|"mounts routes"| node_face_routes
node_face_routes -->|"handles video"| node_video_service
node_face_api -->|"warms detector"| node_video_service
node_video_service -->|"analyzes frames"| node_face_models
node_video_service -->|"stores captures"| node_face_storage

click node_webapp "https://github.com/ndktu/ndktu-student-face-platform/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/ndktu/ndktu-student-face-platform/blob/main/frontend/src/context/AuthContext.tsx"
click node_webpages "https://github.com/ndktu/ndktu-student-face-platform/tree/main/frontend/src/pages"
click node_webservices "https://github.com/ndktu/ndktu-student-face-platform/tree/main/frontend/src/services"
click node_backend "https://github.com/ndktu/ndktu-student-face-platform/blob/main/backend/app/main.py"
click node_api_router "https://github.com/ndktu/ndktu-student-face-platform/blob/main/backend/app/modules/router.py"
click node_auth "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/auth"
click node_org "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/organization_structure"
click node_courses "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/course"
click node_quizzes "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/quiz"
click node_psych "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/psychology"
click node_announcements "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/announcement"
click node_files "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/file"
click node_database "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/core/database"
click node_eduplan "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/integration/eduplan"
click node_zoom "https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/integration/zoom"
click node_face_api "https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/main.py"
click node_face_routes "https://github.com/ndktu/ndktu-student-face-platform/tree/main/face-detection/app/api/v1"
click node_video_service "https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/services/video_service.py"
click node_face_models "https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/services/face_detector.py"
click node_face_storage "https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/utils/face_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_webapp,node_authui,node_webpages,node_webservices,node_user toneBlue
class node_backend,node_api_router,node_auth,node_org,node_database toneAmber
class node_courses,node_quizzes,node_psych,node_announcements,node_files toneMint
class node_eduplan,node_zoom toneRose
class node_face_api,node_face_routes,node_video_service,node_face_models,node_face_storage,node_eduplan_service toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/ndktu/ndktu-student-face-platform/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/ndktu/ndktu-student-face-platform/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Role-based pages](https://github.com/ndktu/ndktu-student-face-platform/tree/main/frontend/src/pages): `frontend/src/pages`
- [API services](https://github.com/ndktu/ndktu-student-face-platform/tree/main/frontend/src/services): `frontend/src/services`

### Platform API

- [API application](https://github.com/ndktu/ndktu-student-face-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/ndktu/ndktu-student-face-platform/blob/main/backend/app/modules/router.py): `backend/app/modules/router.py`
- [Identity and access](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/auth): `backend/app/modules/auth`
- [Organization structure](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/organization_structure): `backend/app/modules/organization_structure`
- [Platform database](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/core/database): `backend/app/core/database`

### Learning services

- [Course delivery](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/course): `backend/app/modules/course`
- [Assessment and quizzes](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/quiz): `backend/app/modules/quiz`
- [Psychology services](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/psychology): `backend/app/modules/psychology`
- [Announcements](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/announcement): `backend/app/modules/announcement`
- [File library](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/file): `backend/app/modules/file`

### Integrations

- [EduPlan integration](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/integration/eduplan): `backend/app/modules/integration/eduplan`
- [Zoom integration](https://github.com/ndktu/ndktu-student-face-platform/tree/main/backend/app/modules/integration/zoom): `backend/app/modules/integration/zoom`

### Face detection

- [Face detection API](https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/main.py): `face-detection/app/main.py`
- [Face endpoints](https://github.com/ndktu/ndktu-student-face-platform/tree/main/face-detection/app/api/v1): `face-detection/app/api/v1`
- [Video analysis](https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/services/video_service.py): `face-detection/app/services/video_service.py`
- [Detection and recognition](https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/services/face_detector.py): `face-detection/app/services/face_detector.py`
- [Captured face storage](https://github.com/ndktu/ndktu-student-face-platform/blob/main/face-detection/app/utils/face_storage.py): `face-detection/app/utils/face_storage.py`

### Other components

- **Platform user**
- **EduPlan service**

## Connections

- Platform user → Web application: uses
- Web application → Auth context: checks identity
- Web application → Role-based pages: routes to
- Role-based pages → API services: requests data
- API services → API application: calls API
- API application → API router: mounts routes
- API router → Identity and access: dispatches
- API router → Organization structure: dispatches
- API router → Course delivery: dispatches
- API router → Assessment and quizzes: dispatches
- API router → Psychology services: dispatches
- API router → Announcements: dispatches
- API router → File library: dispatches
- Identity and access → Platform database: reads and writes
- Organization structure → Platform database: reads and writes
- Course delivery → Platform database: reads and writes
- Assessment and quizzes → Platform database: reads and writes
- Psychology services → Platform database: reads and writes
- Announcements → Platform database: reads and writes
- File library → Platform database: records file metadata
- EduPlan integration → EduPlan service: authenticates with
- API router → EduPlan integration: dispatches
- API router → Zoom integration: dispatches
- Face detection API → Face endpoints: mounts routes
- Face endpoints → Video analysis: handles video
- Face detection API → Video analysis: warms detector
- Video analysis → Detection and recognition: analyzes frames
- Video analysis → Captured face storage: stores captures