How duongnotnhan/onlinetest works
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: app.py Flask app · client.ts API client · Layout.tsx App shell · __init__.py Models
Components 27
Backend
Flask API, services, data access, and operational scripts
- Flask app · Application entrypoint and Flask setup
backend/app.py - Config · Environment-driven secrets, database, and mail settings
backend/config.py - Auth API · Login, verification, and credential-related endpoints
backend/app/routes/auth.py - Admin API · Admin management and orchestration endpoints
backend/app/routes/admin.py - Exam API · Exam composition and delivery endpoints
backend/app/routes/exam.py - Grading API · Essay and grading workflow endpoints
backend/app/routes/grading.py - Result API · Score and result retrieval endpoints
backend/app/routes/result.py - Teacher API · Teacher workflow and roster endpoints
backend/app/routes/teacher.py - Import/Export · Bulk upload and downloadable output endpoints
backend/app/routes/upload.py - Exam service · Exam generation and workflow logic
backend/app/services/exam_service.py - Section service · Exam section handling and composition logic
backend/app/services/exam_section_service.py - Teacher service · Teacher management and supervision logic
backend/app/services/teacher_service.py - Admin service · Admin management and reporting logic
backend/app/services/admin_service.py - Rich text · Formatting and rich-text handling for exam content
backend/app/services/rich_text_service.py - Models · Persistent domain entities and ORM mappings
backend/app/models/__init__.py - Security utils · CAPTCHA and validation helpers
backend/app/utils/validators.py - MySQL · MariaDB/MySQL persistent store
Frontend
React/Vite SPA and role-based screens
- SPA · Single-page client for role-based exam workflows
frontend/src/App.tsx - API client · Centralized HTTP layer for backend calls
frontend/src/api/client.ts - Auth store · Client-side authentication and session state
frontend/src/store/authStore.ts - App shell · Shared navbar, sidebar, and layout framing
frontend/src/components/Layout.tsx - Auth pages · Login, password change, and 2FA setup screens
frontend/src/pages/LoginPage.tsx - Admin area · Admin dashboard and management screens
frontend/src/pages/admin/DashboardPage.tsx - Teacher area · Teacher dashboard, students, and essay grading
frontend/src/pages/teacher/DashboardPage.tsx - Student area · Student dashboard and exam-taking screens
frontend/src/pages/student/DashboardPage.tsx
Ops
Bootstrap and maintenance scripts
- Migrations · Schema migration and verification scripts
backend/run_migrations.py - Bootstrap · Script for creating an initial admin user
create_admin.py
Connections 34
- 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