# tian1003/mr_backend architecture

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

- Interactive diagram: https://gitdiagram.com/tian1003/mr_backend
- Repository: https://github.com/tian1003/mr_backend

## Overview

##### Project type and purpose
- This is a Flask-based RESTful backend (“MR_backend”) for an educational/testing system. It exposes HTTP JSON APIs to manage classes, questions, practices/tests, students, etc., persists data in MySQL, and provides migration and seeding capabilities.

##### File structure
- **Entry point**: wsgi.py
- **Configuration**: `.env.example`, `alembic.ini`
- **App package** (`app/`):
- `blueprints/` (Flask controllers – one per resource)
- `validation/` (request schema definitions)
- `services/` (business logic)
- `daos/` (database access layer)
- `models/` (SQLAlchemy ORM classes)
- `dtos/` (data-transfer objects for response shaping)
- `utilities/`, `bcrypt.py`, `login_manager.py`, `generators/`
- `database.py` (SQLAlchemy setup)
- `seeds/` (data seeders)
- **Migration**: Alembic (`migration/` folder)
- **Init scripts**: `initial_db.py`, JSON fixtures under `init_data/`
- **Tests**: Unit & functional under `tests/`
- **Other scripts**: `excel_reader.py`, `pdf_reader.py`

##### Key insights from README
- Python 3.8+, MySQL 8
- `initial_db.py` runs Alembic migrations and seeds
- Flask-run with auto-reload via wsgi.py
- Optional API docs in a separate folder (not shown)

##### Main components & interactions
a. **Clients** (Browser, mobile app, Postman)
b. **Entry layer** (Flask/Werkzeug WSGI in wsgi.py)
c. **Controller layer** (Blueprints: route definitions)
d. **Validation layer** (Marshmallow schemas)
e. **Service layer** (business logic, orchestration)
f. **DAO layer** (CRUD operations via SQLAlchemy session)
g. **Model layer** (ORM classes mapping to MySQL tables)
i. **Database** (MySQL)
j. **Migration tool** (Alembic) & **Seeder** (Flask-seed)
k. **Utilities** (hashing, data generators, file readers)

Flow example:
HTTP Request → WSGI → Blueprint.route
→ validate input against Schema
→ Service.method(...)
→ DAO.query/insert/update
→ MySQL
← ORM model
← DTO.format(model)
← JSON Response

##### Architectural patterns & principles
- Layered (presentation → validation → service → DAO → persistence)
- Separation of concerns (controllers don’t know SQL, services don’t handle HTTP)
- Dependency injection via central `app/__init__.py` and `database.py`
- Migrations + seeders automate schema evolution and test data
- Test harness isolated under `tests/`

##### Elements
- Controllers (e.g., blue rectangles)
- Services (green)
- DAOs (orange)
- Models/DB (grey)
- Utilities/Generators (light)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Clients (Browser/Mobile/Postman)"]:::external

    %% Entry Layer
    WSGI["WSGI / Flask Entry (wsgi.py)"]:::entry

    %% Controller Layer
    subgraph "Controller Layer"
        Blueprints["Blueprints\n(app/blueprints)"]:::controller
    end

    %% Validation Layer
    Validation["Validation\n(app/validation)"]:::validation

    %% Service Layer
    Services["Services\n(app/services)"]:::service

    %% DAO Layer
    DAOs["DAOs\n(app/daos)"]:::dao

    %% Model & DTO Layer
    subgraph "Model & DTO Layer"
        Models["ORM Models\n(app/models)"]:::model
        DTOs["DTOs\n(app/dtos)"]:::dto
    end

    %% Database Setup
    DatabaseSetup["Database Setup\n(app/database.py)"]:::setup

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

    %% Migration & Seeding
    Migration["Alembic Migrations\n(migration/)"]:::migration
    Seeds["Database Seeders\n(app/seeds/)"]:::seeder
    InitialDB["Initial DB Script\n(initial_db.py)"]:::seeder

    %% Utilities
    Utilities["Utilities & Generators\n(app/utilities, bcrypt, generators, readers)"]:::utility

    %% Tests
    Tests["Tests\n(tests/)"]:::test

    %% Flow
    Client --> WSGI
    WSGI --> Blueprints
    Blueprints --> Validation
    Validation --> Services
    Services --> DAOs
    DAOs --> Models
    Models --> DB
    Services --> DTOs
    DTOs --> WSGI

    %% Side tools
    Migration -.-> DB
    Seeds -.-> DB
    InitialDB -.-> Migration
    InitialDB -.-> Seeds
    DatabaseSetup --> DB
    Utilities --> Services
    Utilities --> DAOs
    Tests --> Blueprints
    Tests --> Services

    %% Click Events
    click WSGI "https://github.com/tian1003/mr_backend/blob/main/wsgi.py"
    click Blueprints "https://github.com/tian1003/mr_backend/tree/main/app/blueprints/"
    click Validation "https://github.com/tian1003/mr_backend/tree/main/app/validation/"
    click Services "https://github.com/tian1003/mr_backend/tree/main/app/services/"
    click DAOs "https://github.com/tian1003/mr_backend/tree/main/app/daos/"
    click Models "https://github.com/tian1003/mr_backend/tree/main/app/models/"
    click DTOs "https://github.com/tian1003/mr_backend/tree/main/app/dtos/"
    click DatabaseSetup "https://github.com/tian1003/mr_backend/blob/main/app/database.py"
    click Migration "https://github.com/tian1003/mr_backend/tree/main/migration/"
    click Seeds "https://github.com/tian1003/mr_backend/tree/main/app/seeds/"
    click InitialDB "https://github.com/tian1003/mr_backend/blob/main/initial_db.py"
    click Utilities "https://github.com/tian1003/mr_backend/blob/main/app/utilities/api_response_helper.py"
    click Tests "https://github.com/tian1003/mr_backend/tree/main/tests/"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef entry fill:#bbf,stroke:#333,stroke-width:1px;
    classDef controller fill:#88f,stroke:#333,stroke-width:1px;
    classDef validation fill:#acf,stroke:#333,stroke-width:1px;
    classDef service fill:#8f8,stroke:#333,stroke-width:1px;
    classDef dao fill:#f96,stroke:#333,stroke-width:1px;
    classDef model fill:#ccc,stroke:#333,stroke-width:1px;
    classDef dto fill:#fc9,stroke:#333,stroke-width:1px;
    classDef db fill:#999,stroke:#333,stroke-width:1px;
    classDef setup fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef migration fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef seeder fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef utility fill:#eef,stroke:#333,stroke-width:1px;
    classDef test fill:#fee,stroke:#333,stroke-width:1px;
```
