# theunknownodysseus/ccc-seb architecture

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

- Interactive diagram: https://gitdiagram.com/theunknownodysseus/ccc-seb
- Repository: https://github.com/theunknownodysseus/ccc-seb

## Overview

CCC Assess is a self-hosted exam platform for administrators to configure question banks, students, exams and results, and for students to take timed MCQ, snippet and coding exams with optional Safe Exam Browser lockdown. The main workflow runs from role-based sign-in through exam management or exam attempt, autosave/submission, evaluation and reporting. The graph separates the React experience, API/domain services, persistence/security and code execution. Several subsystem links rely on the README or source-index references because their implementations were not excerpted.

Main entry points: [`backend/app/main.py`](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/main.py) (FastAPI application), [`backend/app/api/student_exam.py`](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/student_exam.py) (Student exam routes), [`backend/app/api/exams.py`](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/exams.py) (Exam management routes), [`backend/app/services/evaluation_service.py`](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/evaluation_service.py) (Answer evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_admin["Admin workspace"]
  node_student["Student exam UI"]
  node_login["Login and SEB entry"]
  node_frontend_services["Frontend API services"]
  node_app_router["Frontend routing<br/>[App.tsx]"]
end

subgraph group_api["API and domain"]
  node_backend_app["FastAPI application<br/>[main.py]"]
  node_auth_api["Authentication routes<br/>[auth.py]"]
  node_exam_api["Exam management routes<br/>[exams.py]"]
  node_question_api["Question bank routes<br/>[questions.py]"]
  node_student_api["Student management routes<br/>[students.py]"]
  node_attempt_api["Student exam routes<br/>[student_exam.py]"]
  node_results_api["Results routes<br/>[results.py]"]
  node_attempts["Attempt lifecycle<br/>[attempt_service.py]"]
  node_exam_domain["Exam services<br/>[exam_service.py]"]
end

subgraph group_security["Security and persistence"]
  node_auth_security["Token authorization<br/>[auth.py]"]
  node_seb_security["SEB verification<br/>[seb.py]"]
  node_database["SQLAlchemy session<br/>[session.py]"]
  node_models["Exam data model<br/>[models.py]"]
  node_audit["Admin audit log<br/>[audit.py]"]
end

subgraph group_grading["Evaluation and reporting"]
  node_evaluation["Answer evaluation"]
  node_grading["Submission grading<br/>[grading_service.py]"]
  node_judge_client["Judge0 client<br/>[judge0_client.py]"]
  node_results["Results analysis<br/>[results_service.py]"]
  node_export["Results export<br/>[results_export.py]"]
end

subgraph group_external["External services"]
  node_judge0{{"Judge0 execution service"}}
end

node_admin_actor(("Administrator"))
node_student_actor(("Student"))
node_seb{{"Safe Exam Browser"}}

node_app_router -->|"routes to"| node_admin
node_app_router -->|"routes to"| node_student
node_app_router -->|"routes to"| node_login
node_admin_actor -.->|"manages exams"| node_admin
node_student_actor -.->|"takes exams"| node_student
node_admin -->|"requests data"| node_frontend_services
node_student -->|"requests data"| node_frontend_services
node_login -->|"authenticates via"| node_frontend_services
node_frontend_services -.->|"calls API"| node_backend_app
node_backend_app -->|"registers routes"| node_auth_api
node_backend_app -->|"registers routes"| node_exam_api
node_backend_app -->|"registers routes"| node_question_api
node_backend_app -->|"registers routes"| node_student_api
node_backend_app -->|"registers routes"| node_attempt_api
node_backend_app -->|"registers routes"| node_results_api
node_auth_api -->|"authenticates with"| node_auth_security
node_attempt_api -->|"manages attempts"| node_attempts
node_attempt_api -->|"evaluates answers"| node_evaluation
node_attempt_api -->|"grades submissions"| node_grading
node_attempt_api -->|"checks lockdown"| node_seb_security
node_seb_security -.->|"verifies client"| node_seb
node_evaluation -->|"submits batches"| node_judge_client
node_grading -->|"evaluates code"| node_evaluation
node_judge_client -.->|"executes code"| node_judge0
node_exam_api -->|"uses services"| node_exam_domain
node_exam_api -->|"starts attempts"| node_attempts
node_exam_api -->|"records actions"| node_audit
node_student_api -->|"records actions"| node_audit
node_results_api -->|"loads results"| node_results
node_results_api -->|"exports results"| node_export
node_auth_security -->|"gets session"| node_database
node_database -->|"provides ORM base"| node_models
node_backend_app -->|"creates tables"| node_database
node_attempts -->|"reads and writes"| node_models
node_evaluation -->|"returns results"| node_judge_client

click node_admin "https://github.com/theunknownodysseus/ccc-seb/tree/master/frontend/src/admin"
click node_student "https://github.com/theunknownodysseus/ccc-seb/tree/master/frontend/src/student"
click node_login "https://github.com/theunknownodysseus/ccc-seb/tree/master/frontend/src/pages"
click node_frontend_services "https://github.com/theunknownodysseus/ccc-seb/tree/master/frontend/src/services"
click node_app_router "https://github.com/theunknownodysseus/ccc-seb/blob/master/frontend/src/App.tsx"
click node_backend_app "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/main.py"
click node_auth_api "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/auth.py"
click node_exam_api "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/exams.py"
click node_question_api "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/questions.py"
click node_student_api "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/students.py"
click node_attempt_api "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/student_exam.py"
click node_results_api "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/results.py"
click node_attempts "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/attempt_service.py"
click node_exam_domain "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/exam_service.py"
click node_auth_security "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/security/auth.py"
click node_seb_security "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/security/seb.py"
click node_database "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/database/session.py"
click node_models "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/models/models.py"
click node_audit "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/audit.py"
click node_evaluation "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/evaluation_service.py"
click node_grading "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/grading_service.py"
click node_judge_client "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/judge0_client.py"
click node_results "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/results_service.py"
click node_export "https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/results_export.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_admin,node_student,node_login,node_frontend_services,node_app_router,node_seb toneBlue
class node_backend_app,node_auth_api,node_exam_api,node_question_api,node_student_api,node_attempt_api,node_results_api,node_attempts,node_exam_domain toneAmber
class node_auth_security,node_seb_security,node_database,node_models,node_audit toneMint
class node_evaluation,node_grading,node_judge_client,node_results,node_export toneRose
class node_judge0,node_admin_actor,node_student_actor toneIndigo
```

## Components

### Web application

- [Admin workspace](https://github.com/theunknownodysseus/ccc-seb/tree/master/frontend/src/admin): `frontend/src/admin`
- [Student exam UI](https://github.com/theunknownodysseus/ccc-seb/tree/master/frontend/src/student): `frontend/src/student`
- [Login and SEB entry](https://github.com/theunknownodysseus/ccc-seb/tree/master/frontend/src/pages): `frontend/src/pages`
- [Frontend API services](https://github.com/theunknownodysseus/ccc-seb/tree/master/frontend/src/services): `frontend/src/services`
- [Frontend routing](https://github.com/theunknownodysseus/ccc-seb/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`

### API and domain

- [FastAPI application](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Exam management routes](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/exams.py): `backend/app/api/exams.py`
- [Question bank routes](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/questions.py): `backend/app/api/questions.py`
- [Student management routes](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/students.py): `backend/app/api/students.py`
- [Student exam routes](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/student_exam.py): `backend/app/api/student_exam.py`
- [Results routes](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/api/results.py): `backend/app/api/results.py`
- [Attempt lifecycle](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/attempt_service.py): `backend/app/services/attempt_service.py`
- [Exam services](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/exam_service.py): `backend/app/services/exam_service.py`

### Security and persistence

- [Token authorization](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/security/auth.py): `backend/app/security/auth.py`
- [SEB verification](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/security/seb.py): `backend/app/security/seb.py`
- [SQLAlchemy session](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/database/session.py): `backend/app/database/session.py`
- [Exam data model](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/models/models.py): `backend/app/models/models.py`
- [Admin audit log](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/audit.py): `backend/app/services/audit.py`

### Evaluation and reporting

- [Answer evaluation](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/evaluation_service.py): `backend/app/services/evaluation_service.py`
- [Submission grading](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/grading_service.py): `backend/app/services/grading_service.py`
- [Judge0 client](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/judge0_client.py): `backend/app/services/judge0_client.py`
- [Results analysis](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/results_service.py): `backend/app/services/results_service.py`
- [Results export](https://github.com/theunknownodysseus/ccc-seb/blob/master/backend/app/services/results_export.py): `backend/app/services/results_export.py`

### External services

- **Judge0 execution service**

### Other components

- **Administrator**
- **Student**
- **Safe Exam Browser**

## Connections

- Frontend routing → Admin workspace: routes to (evidence: `frontend/src/App.tsx`)
- Frontend routing → Student exam UI: routes to (evidence: `frontend/src/App.tsx`)
- Frontend routing → Login and SEB entry: routes to (evidence: `frontend/src/App.tsx`)
- Administrator → Admin workspace: manages exams (evidence: `README.md`)
- Student → Student exam UI: takes exams (evidence: `README.md`)
- Admin workspace → Frontend API services: requests data (evidence: `frontend/src/admin/ExamsPage.tsx`)
- Student exam UI → Frontend API services: requests data (evidence: `frontend/src/student/ExamTakingPage.tsx`)
- Login and SEB entry → Frontend API services: authenticates via (evidence: `frontend/src/pages/LoginPage.tsx`)
- Frontend API services → FastAPI application: calls API
- FastAPI application → Authentication routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Exam management routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Question bank routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Student management routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Student exam routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Results routes: registers routes (evidence: `backend/app/main.py`)
- Authentication routes → Token authorization: authenticates with (evidence: `backend/app/api/auth.py`)
- Student exam routes → Attempt lifecycle: manages attempts (evidence: `backend/app/api/student_exam.py`)
- Student exam routes → Answer evaluation: evaluates answers (evidence: `backend/app/api/student_exam.py`)
- Student exam routes → Submission grading: grades submissions (evidence: `backend/app/api/student_exam.py`)
- Student exam routes → SEB verification: checks lockdown (evidence: `backend/app/api/student_exam.py`)
- SEB verification → Safe Exam Browser: verifies client
- Answer evaluation → Judge0 client: submits batches (evidence: `backend/app/services/evaluation_service.py`)
- Submission grading → Answer evaluation: evaluates code (evidence: `backend/app/services/grading_service.py`)
- Judge0 client → Judge0 execution service: executes code
- Exam management routes → Exam services: uses services (evidence: `backend/app/api/exams.py`)
- Exam management routes → Attempt lifecycle: starts attempts (evidence: `backend/app/api/exams.py`)
- Exam management routes → Admin audit log: records actions (evidence: `backend/app/api/exams.py`)
- Student management routes → Admin audit log: records actions (evidence: `backend/app/api/students.py`)
- Results routes → Results analysis: loads results (evidence: `backend/app/api/results.py`)
- Results routes → Results export: exports results (evidence: `backend/app/api/results.py`)
- Token authorization → SQLAlchemy session: gets session (evidence: `backend/app/security/auth.py`)
- SQLAlchemy session → Exam data model: provides ORM base (evidence: `backend/app/models/models.py`)
- FastAPI application → SQLAlchemy session: creates tables (evidence: `backend/app/main.py`)
- Attempt lifecycle → Exam data model: reads and writes (evidence: `backend/app/services/attempt_service.py`)
- Answer evaluation → Judge0 client: returns results (evidence: `backend/app/services/evaluation_service.py`)
