# duongnotnhan/onlinetest architecture

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

- Interactive diagram: https://gitdiagram.com/duongnotnhan/onlinetest
- Repository: https://github.com/duongnotnhan/onlinetest

## Overview

1. This repository is a two-tier exam management system: a Flask backend exposes domain APIs, and a React/Vite frontend provides the user interface. The business domain is a Vietnamese high-school graduation exam simulator, with distinct workflows for admin, teacher, and student roles.

2. The backend is the system core. `backend/app.py` bootstraps the Flask application, while `backend/config.py` and `.env` supply database, secret, and optional mail settings. Persistent state lives in MariaDB/MySQL, accessed through SQLAlchemy models and managed with Flask migrations/seed scripts.

3. Backend HTTP boundaries are organized by feature routes under `backend/app/routes/`: authentication, admin management, exams, grading, results, student, teacher, upload, and export. This indicates the API is split by domain rather than by UI page, and each route module is the entry point for a slice of the workflow.

4. The service layer under `backend/app/services/` holds the main business logic. `exam_service`, `exam_section_service`, `grading`, `teacher_service`, `admin_service`, and `rich_text_service` suggest that routes are thin controllers delegating to reusable domain services for exam composition, section handling, grading workflows, teacher/admin operations, and content formatting.

5. Authentication and security are first-class concerns. The frontend includes login, password change, and two-factor setup pages, while the backend has auth routes plus utilities for CAPTCHA and validation. That implies the system supports credential-based login with extra verification and input validation around sensitive actions.

6. Role separation is explicit in the UI structure. The frontend has dedicated page groups for `admin`, `teacher`, and `student`, each with its own dashboard and task-specific screens. This maps cleanly to backend route domains and suggests role-based authorization governs both navigation and API access.

7. The student flow is centered on taking exams and viewing outcomes. The student dashboard and `TakeExamPage` on the frontend likely consume exam-generation and submission APIs from the backend, then receive scored results through the results route. This is the core transactional path of the system.

8. The teacher flow focuses on supervision and essay grading. Teacher pages include a dashboard, student list, and `GradeEssayPage`, which aligns with backend grading and teacher services. This indicates a mixed grading model: automated handling for objective parts and manual review for essay components.

9. The admin flow handles system administration and content lifecycle. Admin pages cover exams, grading assignments, results, schools, students, teachers, and a dashboard. That corresponds to the backend’s admin, export, and management routes, making admin the orchestration layer for users, exam setup, and reporting.

10. Data import/export is a distinct subsystem. The backend has `upload` and `export` routes, implying bulk ingestion of exam-related assets or user data and generation of downloadable outputs such as reports or result files. This is likely where file handling crosses the HTTP boundary.

11. The frontend is a single-page application built with React, TypeScript, Tailwind, and Vite. `src/api/client.ts` and `src/api/index.ts` centralize backend calls, `src/store/authStore.ts` holds authentication state, and shared layout components (`Navbar`, `Sidebar`, `Layout`) provide the app shell for role-based navigation.

12. Operationally, the repo includes setup and maintenance scripts rather than a separate orchestration service. `run_migrations.py`, `verify_schema.py`, and `create_admin.py` support database initialization and bootstrap tasks, showing that deployment assumes a manually prepared MySQL schema plus application-level seeding and admin creation.

13. In architecture diagram terms, the key boundaries are: browser SPA → API client → Flask route layer → service layer → SQLAlchemy/MySQL, with supporting utilities for auth/validation/uploads and optional mail/captcha features. The most important flows are login/authentication, exam delivery, exam submission, grading, result retrieval, and admin/teacher management.

Main entry points: [`backend/app.py`](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app.py) (Flask app), [`frontend/src/api/client.ts`](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/api/client.ts) (API client), [`frontend/src/components/Layout.tsx`](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/components/Layout.tsx) (App shell), [`backend/app/models/__init__.py`](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/models/__init__.py) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_flask_app["Flask app<br/>api bootstrap<br/>[app.py]"]
  node_config["Config<br/>[config.py]"]
  node_auth_routes["Auth API<br/>route module<br/>[auth.py]"]
  node_admin_routes["Admin API<br/>route module<br/>[admin.py]"]
  node_exam_routes["Exam API<br/>route module<br/>[exam.py]"]
  node_grading_routes["Grading API<br/>route module<br/>[grading.py]"]
  node_result_routes["Result API<br/>route module<br/>[result.py]"]
  node_teacher_routes["Teacher API<br/>route module<br/>[teacher.py]"]
  node_upload_export["Import/Export<br/>route module<br/>[upload.py]"]
  node_exam_service["Exam service<br/>domain service<br/>[exam_service.py]"]
  node_section_service["Section service<br/>domain service"]
  node_teacher_service["Teacher service<br/>domain service<br/>[teacher_service.py]"]
  node_admin_service["Admin service<br/>domain service<br/>[admin_service.py]"]
  node_rich_text_service["Rich text<br/>content service"]
  node_models[("Models<br/>[__init__.py]")]
  node_utils["Security utils<br/>utility layer<br/>[validators.py]"]
  node_database[("MySQL<br/>database")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA<br/>react-vite app<br/>[App.tsx]"]
  node_api_client["API client<br/>frontend api<br/>[client.ts]"]
  node_auth_store["Auth store<br/>state store<br/>[authStore.ts]"]
  node_shell["App shell<br/>layout<br/>[Layout.tsx]"]
  node_login_pages["Auth pages<br/>ui pages<br/>[LoginPage.tsx]"]
  node_admin_ui["Admin area<br/>ui pages<br/>[DashboardPage.tsx]"]
  node_teacher_ui["Teacher area<br/>ui pages<br/>[DashboardPage.tsx]"]
  node_student_ui["Student area<br/>ui pages<br/>[DashboardPage.tsx]"]
end

subgraph group_ops["Ops"]
  node_migrations["Migrations<br/>maintenance scripts<br/>[run_migrations.py]"]
  node_bootstrap["Bootstrap<br/>admin script<br/>[create_admin.py]"]
end

node_frontend_app -->|"renders"| node_shell
node_shell -->|"navigates"| node_login_pages
node_shell -->|"navigates"| node_admin_ui
node_shell -->|"navigates"| node_teacher_ui
node_shell -->|"navigates"| node_student_ui
node_frontend_app -->|"calls"| node_api_client
node_api_client -->|"requests"| node_auth_routes
node_api_client -->|"requests"| node_exam_routes
node_api_client -->|"requests"| node_grading_routes
node_api_client -->|"requests"| node_result_routes
node_api_client -->|"requests"| node_admin_routes
node_api_client -->|"requests"| node_teacher_routes
node_api_client -->|"requests"| node_upload_export
node_flask_app -->|"loads"| node_config
node_flask_app -->|"registers"| node_auth_routes
node_flask_app -->|"registers"| node_admin_routes
node_flask_app -->|"registers"| node_exam_routes
node_flask_app -->|"registers"| node_grading_routes
node_flask_app -->|"registers"| node_result_routes
node_flask_app -->|"registers"| node_teacher_routes
node_flask_app -->|"registers"| node_upload_export
node_auth_routes -->|"validates"| node_utils
node_admin_routes -->|"delegates"| node_admin_service
node_teacher_routes -->|"delegates"| node_teacher_service
node_exam_routes -->|"delegates"| node_exam_service
node_exam_routes -->|"delegates"| node_section_service
node_grading_routes -->|"formats"| node_rich_text_service
node_exam_service -->|"reads/writes"| node_models
node_section_service -->|"reads/writes"| node_models
node_teacher_service -->|"reads/writes"| node_models
node_admin_service -->|"reads/writes"| node_models
node_models -->|"stores"| node_database
node_migrations -->|"migrates"| node_database
node_bootstrap -->|"seeds"| node_database

click node_frontend_app "https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/api/client.ts"
click node_auth_store "https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/store/authStore.ts"
click node_shell "https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/components/Layout.tsx"
click node_login_pages "https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/pages/LoginPage.tsx"
click node_admin_ui "https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/pages/admin/DashboardPage.tsx"
click node_teacher_ui "https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/pages/teacher/DashboardPage.tsx"
click node_student_ui "https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/pages/student/DashboardPage.tsx"
click node_flask_app "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app.py"
click node_config "https://github.com/duongnotnhan/onlinetest/blob/main/backend/config.py"
click node_auth_routes "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/auth.py"
click node_admin_routes "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/admin.py"
click node_exam_routes "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/exam.py"
click node_grading_routes "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/grading.py"
click node_result_routes "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/result.py"
click node_teacher_routes "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/teacher.py"
click node_upload_export "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/upload.py"
click node_exam_service "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/exam_service.py"
click node_section_service "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/exam_section_service.py"
click node_teacher_service "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/teacher_service.py"
click node_admin_service "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/admin_service.py"
click node_rich_text_service "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/rich_text_service.py"
click node_models "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/models/__init__.py"
click node_utils "https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/utils/validators.py"
click node_migrations "https://github.com/duongnotnhan/onlinetest/blob/main/backend/run_migrations.py"
click node_bootstrap "https://github.com/duongnotnhan/onlinetest/blob/main/create_admin.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_flask_app,node_config,node_auth_routes,node_admin_routes,node_exam_routes,node_grading_routes,node_result_routes,node_teacher_routes,node_upload_export,node_exam_service,node_section_service,node_teacher_service,node_admin_service,node_rich_text_service,node_models,node_utils,node_database toneBlue
class node_frontend_app,node_api_client,node_auth_store,node_shell,node_login_pages,node_admin_ui,node_teacher_ui,node_student_ui toneAmber
class node_migrations,node_bootstrap toneMint
```

## Components

### Backend

Flask API, services, data access, and operational scripts

- [Flask app](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app.py): api bootstrap · Application entrypoint and Flask setup · `backend/app.py`
- [Config](https://github.com/duongnotnhan/onlinetest/blob/main/backend/config.py): runtime config · Environment-driven secrets, database, and mail settings · `backend/config.py`
- [Auth API](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/auth.py): route module · Login, verification, and credential-related endpoints · `backend/app/routes/auth.py`
- [Admin API](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/admin.py): route module · Admin management and orchestration endpoints · `backend/app/routes/admin.py`
- [Exam API](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/exam.py): route module · Exam composition and delivery endpoints · `backend/app/routes/exam.py`
- [Grading API](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/grading.py): route module · Essay and grading workflow endpoints · `backend/app/routes/grading.py`
- [Result API](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/result.py): route module · Score and result retrieval endpoints · `backend/app/routes/result.py`
- [Teacher API](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/teacher.py): route module · Teacher workflow and roster endpoints · `backend/app/routes/teacher.py`
- [Import/Export](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/routes/upload.py): route module · Bulk upload and downloadable output endpoints · `backend/app/routes/upload.py`
- [Exam service](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/exam_service.py): domain service · Exam generation and workflow logic · `backend/app/services/exam_service.py`
- [Section service](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/exam_section_service.py): domain service · Exam section handling and composition logic · `backend/app/services/exam_section_service.py`
- [Teacher service](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/teacher_service.py): domain service · Teacher management and supervision logic · `backend/app/services/teacher_service.py`
- [Admin service](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/admin_service.py): domain service · Admin management and reporting logic · `backend/app/services/admin_service.py`
- [Rich text](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/services/rich_text_service.py): content service · Formatting and rich-text handling for exam content · `backend/app/services/rich_text_service.py`
- [Models](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/models/__init__.py): sqlalchemy models · Persistent domain entities and ORM mappings · `backend/app/models/__init__.py`
- [Security utils](https://github.com/duongnotnhan/onlinetest/blob/main/backend/app/utils/validators.py): utility layer · CAPTCHA and validation helpers · `backend/app/utils/validators.py`
- **MySQL**: database · MariaDB/MySQL persistent store

### Frontend

React/Vite SPA and role-based screens

- [SPA](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/App.tsx): react-vite app · Single-page client for role-based exam workflows · `frontend/src/App.tsx`
- [API client](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/api/client.ts): frontend api · Centralized HTTP layer for backend calls · `frontend/src/api/client.ts`
- [Auth store](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/store/authStore.ts): state store · Client-side authentication and session state · `frontend/src/store/authStore.ts`
- [App shell](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/components/Layout.tsx): layout · Shared navbar, sidebar, and layout framing · `frontend/src/components/Layout.tsx`
- [Auth pages](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/pages/LoginPage.tsx): ui pages · Login, password change, and 2FA setup screens · `frontend/src/pages/LoginPage.tsx`
- [Admin area](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/pages/admin/DashboardPage.tsx): ui pages · Admin dashboard and management screens · `frontend/src/pages/admin/DashboardPage.tsx`
- [Teacher area](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/pages/teacher/DashboardPage.tsx): ui pages · Teacher dashboard, students, and essay grading · `frontend/src/pages/teacher/DashboardPage.tsx`
- [Student area](https://github.com/duongnotnhan/onlinetest/blob/main/frontend/src/pages/student/DashboardPage.tsx): ui pages · Student dashboard and exam-taking screens · `frontend/src/pages/student/DashboardPage.tsx`

### Ops

Bootstrap and maintenance scripts

- [Migrations](https://github.com/duongnotnhan/onlinetest/blob/main/backend/run_migrations.py): maintenance scripts · Schema migration and verification scripts · `backend/run_migrations.py`
- [Bootstrap](https://github.com/duongnotnhan/onlinetest/blob/main/create_admin.py): admin script · Script for creating an initial admin user · `create_admin.py`

## Connections

- SPA → App shell: renders · The SPA is framed by shared layout components
- App shell → Auth pages: navigates · Auth-related views are shown within the app shell
- App shell → Admin area: navigates · Admin screens are rendered through the shared shell
- App shell → Teacher area: navigates · Teacher screens are rendered through the shared shell
- App shell → Student area: navigates · Student screens are rendered through the shared shell
- SPA → API client: calls · UI uses the centralized API client for backend access
- API client → Auth API: requests · Authentication and verification requests hit auth endpoints
- API client → Exam API: requests · Exam-taking and exam-management requests hit exam endpoints
- API client → Grading API: requests · Grading actions are sent to grading endpoints
- API client → Result API: requests · Result views are loaded from result endpoints
- API client → Admin API: requests · Admin management screens call admin endpoints
- API client → Teacher API: requests · Teacher screens call teacher endpoints
- API client → Import/Export: requests · Bulk file transfer and export flows use dedicated endpoints
- Flask app → Config: loads · Flask startup is driven by environment configuration
- Flask app → Auth API: registers · Auth blueprint is mounted into the Flask app
- Flask app → Admin API: registers · Admin blueprint is mounted into the Flask app
- Flask app → Exam API: registers · Exam blueprint is mounted into the Flask app
- Flask app → Grading API: registers · Grading blueprint is mounted into the Flask app
- Flask app → Result API: registers · Result blueprint is mounted into the Flask app
- Flask app → Teacher API: registers · Teacher blueprint is mounted into the Flask app
- Flask app → Import/Export: registers · Upload/export blueprint is mounted into the Flask app
- Auth API → Security utils: validates · Sensitive auth inputs use validation and captcha helpers
- Admin API → Admin service: delegates · Admin endpoints delegate to domain service logic
- Teacher API → Teacher service: delegates · Teacher endpoints delegate to domain service logic
- Exam API → Exam service: delegates · Exam endpoints delegate to exam workflow logic
- Exam API → Section service: delegates · Section-level exam composition is handled separately
- Grading API → Rich text: formats · Grading content may use rich-text handling
- Exam service → Models: reads/writes · Exam workflows persist and query ORM entities
- Section service → Models: reads/writes · Section composition is backed by ORM entities
- Teacher service → Models: reads/writes · Teacher workflows persist and query ORM entities
- Admin service → Models: reads/writes · Admin workflows persist and query ORM entities
- Models → MySQL: stores · ORM models map to the MariaDB/MySQL database
- Migrations → MySQL: migrates · Schema scripts prepare and verify the database
- Bootstrap → MySQL: seeds · Initial admin bootstrap depends on the database
