# sahil-kg7/testmaker architecture

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

- Interactive diagram: https://gitdiagram.com/sahil-kg7/testmaker
- Repository: https://github.com/sahil-kg7/testmaker

## Overview

##### Project Type and Purpose
- This is a RESTful backend service (“testmaker”) implemented in Python using FastAPI.
- Purpose: allow users to assemble test papers from a pool of questions (MCQ, fill-in, short answer, etc.), persisting data in a MySQL database, and offering utilities for backups.

##### File Structure
- Top-level:
- app.py – FastAPI application entrypoint
- app_config.ini / db_config.py – configuration files for application and database
- controllers/ – HTTP endpoint definitions (API layer)
- services/ – business logic layer
- db/ – repository/data access layer
- models/ – in-memory and ORM models (SQLModel)
- utils/ – logging, backup scripts, other helpers
- enums/ & exceptions/ – domain enums and custom error types
- backups/ – SQL dump snapshots
- Layering pattern: Controllers → Services → Repositories → Database

##### Extract Insights from README
- Tech stack: FastAPI for HTTP API, SQLModel (built on Pydantic + SQLAlchemy) for ORM, MySQL as RDBMS.
- No frontend/UI component—solely a backend microservice.

a. Main Components
- API Layer (FastAPI app.py)
- Controller Modules (ClassController, TestController, etc.)
- Service Layer (ClassService, TestService, etc.)
- Data Access Layer (ClassRepo, TestRepo, etc.)
- Database (MySQL instance)
- Utility Scripts (mysql_backup_script)
- Configuration (app_config.ini, db_config.py)
- Supporting Modules (Enums, Exceptions, Logging)
b. Relationships & Data Flow
1. Client → HTTP Request → FastAPI Routing in app.py
2. Routing → Controller → Service Layer
3. Service Layer applies business rules → calls Repository
4. Repository uses SQLModel → executes SQL on MySQL
5. Database returns records → Repository → Service → Controller → HTTP Response
6. Backup script (utils/mysql_backup_script) connects to MySQL for dumps
c. Architectural Patterns & Principles
- Layered Architecture (API, Service, Repository)
- Repository Pattern for data access
- Separation of Concerns: controllers handle transport, services handle logic, repos handle persistence
- Use of Pydantic/SQLModel for data validation
d. Key Technologies
- FastAPI (ASGI web framework)
- SQLModel / SQLAlchemy (ORM layer)
- MySQL (persistent storage)
- Python modules: enums, custom exceptions, logging utilities

##### Detail
- Exception and logging utilities as supportive side-nodes that hook into controllers/services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration"
        direction TB
        AppConfig["app_config.ini"]:::config
        DBConfig["db_config.py"]:::config
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIEntrypoint["app.py"]:::api
        ClassController["ClassController"]:::api
        QuestionController["QuestionController"]:::api
        SchoolController["SchoolController"]:::api
        SubjectController["SubjectController"]:::api
        TestController["TestController"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ClassService["ClassService"]:::service
        QuestionService["QuestionService"]:::service
        SchoolService["SchoolService"]:::service
        SubjectService["SubjectService"]:::service
        TestService["TestService"]:::service
    end

    %% Repository Layer
    subgraph "Data Access Layer"
        direction TB
        ClassRepo["ClassRepo"]:::repo
        QuestionRepo["QuestionRepo"]:::repo
        SchoolRepo["SchoolRepo"]:::repo
        SubjectRepo["SubjectRepo"]:::repo
        TestRepo["TestRepo"]:::repo
    end

    %% Database
    DB[("MySQL Database")]:::db

    %% Utilities & Support
    subgraph "Utilities & Support"
        direction TB
        Logging["Logging Utilities"]:::util
        Exceptions["Custom Exceptions"]:::support
        Enums["QuestionTypeEnum"]:::support
        BackupScript["mysql_backup_script"]:::util
    end

    %% Relationships
    Client["HTTP Client"]:::external -->|Sends API Request| APIEntrypoint
    AppConfig -->|Loads Config| APIEntrypoint
    DBConfig -->|DB Settings| ClassRepo
    APIEntrypoint -->|"routes to"| ClassController
    APIEntrypoint -->|"routes to"| QuestionController
    APIEntrypoint -->|"routes to"| SchoolController
    APIEntrypoint -->|"routes to"| SubjectController
    APIEntrypoint -->|"routes to"| TestController

    ClassController -->|"calls"| ClassService
    QuestionController -->|"calls"| QuestionService
    SchoolController -->|"calls"| SchoolService
    SubjectController -->|"calls"| SubjectService
    TestController -->|"calls"| TestService

    ClassService -->|"uses"| ClassRepo
    QuestionService -->|"uses"| QuestionRepo
    SchoolService -->|"uses"| SchoolRepo
    SubjectService -->|"uses"| SubjectRepo
    TestService -->|"uses"| TestRepo

    ClassRepo -->|"executes SQL"| DB
    QuestionRepo -->|"executes SQL"| DB
    SchoolRepo -->|"executes SQL"| DB
    SubjectRepo -->|"executes SQL"| DB
    TestRepo -->|"executes SQL"| DB

    BackupScript -->|"connects to"| DB
    Logging -->|"logs from"| ClassController
    Logging -->|"logs from"| QuestionController
    Logging -->|"logs from"| SchoolController
    Logging -->|"logs from"| SubjectController
    Logging -->|"logs from"| TestController
    Exceptions -->|"thrown by"| ClassService
    Exceptions -->|"thrown by"| QuestionService

    %% Click Events
    click APIEntrypoint "https://github.com/sahil-kg7/testmaker/blob/main/app.py"
    click AppConfig "https://github.com/sahil-kg7/testmaker/blob/main/app_config.ini"
    click DBConfig "https://github.com/sahil-kg7/testmaker/blob/main/db_config.py"
    click ClassController "https://github.com/sahil-kg7/testmaker/blob/main/controllers/ClassController.py"
    click QuestionController "https://github.com/sahil-kg7/testmaker/blob/main/controllers/QuestionController.py"
    click SchoolController "https://github.com/sahil-kg7/testmaker/blob/main/controllers/SchoolController.py"
    click SubjectController "https://github.com/sahil-kg7/testmaker/blob/main/controllers/SubjectController.py"
    click TestController "https://github.com/sahil-kg7/testmaker/blob/main/controllers/TestController.py"
    click ClassService "https://github.com/sahil-kg7/testmaker/blob/main/services/ClassService.py"
    click QuestionService "https://github.com/sahil-kg7/testmaker/blob/main/services/QuestionService.py"
    click SchoolService "https://github.com/sahil-kg7/testmaker/blob/main/services/SchoolService.py"
    click SubjectService "https://github.com/sahil-kg7/testmaker/blob/main/services/SubjectService.py"
    click TestService "https://github.com/sahil-kg7/testmaker/blob/main/services/TestService.py"
    click ClassRepo "https://github.com/sahil-kg7/testmaker/blob/main/db/ClassRepo.py"
    click QuestionRepo "https://github.com/sahil-kg7/testmaker/blob/main/db/QuestionRepo.py"
    click SchoolRepo "https://github.com/sahil-kg7/testmaker/blob/main/db/SchoolRepo.py"
    click SubjectRepo "https://github.com/sahil-kg7/testmaker/blob/main/db/SubjectRepo.py"
    click TestRepo "https://github.com/sahil-kg7/testmaker/blob/main/db/TestRepo.py"
    click Enums "https://github.com/sahil-kg7/testmaker/blob/main/enums/QuestionTypeEnum.py"
    click Exceptions "https://github.com/sahil-kg7/testmaker/blob/main/exceptions/custom_exceptions.py"
    click Logging "https://github.com/sahil-kg7/testmaker/blob/main/utils/logging_utils.py"
    click BackupScript "https://github.com/sahil-kg7/testmaker/blob/main/utils/mysql_backup_script.py"
    click DB "https://github.com/sahil-kg7/testmaker/blob/main/backups/test_maker_2025-06-07_01-04-03.sql"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#000;
    classDef service fill:#D0FFD0,stroke:#000;
    classDef repo fill:#FFE3B8,stroke:#000;
    classDef db fill:#D3D3D3,stroke:#000;
    classDef util fill:#FFFACD,stroke:#000;
    classDef config fill:#E6E6FA,stroke:#000;
    classDef support fill:#F0F0F0,stroke:#000;
    classDef external fill:#FFFFFF,stroke:#000,stroke-dasharray: 5 5;
```
