# 7s9n/small_sms_api architecture

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

- Interactive diagram: https://gitdiagram.com/7s9n/small_sms_api
- Repository: https://github.com/7s9n/small_sms_api

## Overview

##### Project type and purpose
- This is a backend‐only RESTful API for a “School Management System,” built with FastAPI and Uvicorn.
- It provides endpoints for managing students, subjects, grades, registrations, school years, nationalities, and user authentication/permissions.
- Alembic is used for database migrations against a PostgreSQL database.

##### File structure
- Top level:
- alembic/… & alembic.ini – migration scripts and config
- app/ – all application code
- requirements.txt, .env.example, README.MD
- app/ substructure:
- api/api_v1/routes – HTTP route definitions (grade, student, subject, etc.)
- api/api_v1/api.py – router aggregation and versioning
- deps.py – dependency‐injection helpers (e.g., DB session, current user)
- core/config.py – environment/configuration settings
- crud/ – repository layer, one class per model encapsulating DB operations
- db/ – session factory and base ORM classes
- models/ – SQLAlchemy ORM model definitions
- schemas/ – Pydantic models for request/response validation
- main.py – FastAPI app instantiation and Uvicorn entry point

##### README
- Confirms it’s a FastAPI service using a .env file for config
- Requires creating a Postgres database, then running Alembic “upgrade head”
- Launch with `uvicorn app.main:app --reload`

a. Main components to include
1. Client(s): Browser, mobile app, Postman, etc.
2. API Gateway/Uvicorn: HTTP server exposing FastAPI endpoints
3. FastAPI Application Layers:
– API Layer (Routers)
– Dependency Layer (`deps.py`)
– Service/Repository Layer (CRUD classes)
– ORM Layer (SQLAlchemy models & session)
– Validation Layer (Pydantic schemas)
4. Configuration (FastAPI Settings via `core/config.py`)
5. Database: PostgreSQL
6. Migration Tool: Alembic

b. Relationships and data flows
- Client → HTTP request → Uvicorn/FastAPI
- FastAPI → Router (app/api/api_v1/routes)
- Router → Dependencies (get_db, get_current_user)
- Handler → CRUD method → Session → Database
- Handler → Pydantic Schema for input/output
- Alembic → reads model metadata → executes migrations on Database

c. Architectural patterns & principles
- Layered architecture (Presentation → API → Service/Repository → Data)
- Dependency Injection (via FastAPI’s Depends)
- Repository pattern (CRUD classes abstract DB operations)
- Separation of concerns (routers vs. business logic vs. data models)

d. Key technologies/frameworks
- FastAPI + Uvicorn (ASGI server)
- Pydantic (request/response validation)
- SQLAlchemy (ORM)
- Alembic (DB migrations)
- PostgreSQL (persistent store)

## Diagram (Mermaid)

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

    %% Entry Point
    Main["Uvicorn / ASGI Server (app/main.py)"]:::api

    %% API Layer
    subgraph "API Layer"
        API["Router Aggregator & Versioning\n(app/api/api_v1/api.py)"]:::api
        subgraph "Routers\n(app/api/api_v1/routes)"
            StudentRouter["StudentRouter"]:::api
            SubjectRouter["SubjectRouter"]:::api
            GradeRouter["GradeRouter"]:::api
            NationalityRouter["NationalityRouter"]:::api
            RegistrationRouter["RegistrationRouter"]:::api
            SchoolYearRouter["SchoolYearRouter"]:::api
        end
    end

    %% Dependency Injection & Configuration
    Deps["Dependency Injection\n(app/deps.py)"]:::api
    Config["Configuration\n(app/core/config.py)"]:::api

    %% Validation Layer
    subgraph "Pydantic Schemas\n(app/schemas)"
        StudentSchema["Student Schema"]:::data
        SubjectSchema["Subject Schema"]:::data
        GradeSchema["Grade Schema"]:::data
        GradeSubjectSchema["Grade-Subject Schema"]:::data
        NationalitySchema["Nationality Schema"]:::data
        RegistrationSchema["Registration Schema"]:::data
        SchoolYearSchema["SchoolYear Schema"]:::data
    end

    %% Service / Repository Layer
    subgraph "CRUD Services\n(app/crud)"
        BaseCRUD["Base CRUD"]:::repo
        StudentCRUD["Student CRUD"]:::repo
        SubjectCRUD["Subject CRUD"]:::repo
        GradeCRUD["Grade CRUD"]:::repo
        GradeSubjectCRUD["Grade-Subject CRUD"]:::repo
        NationalityCRUD["Nationality CRUD"]:::repo
        RegistrationCRUD["Registration CRUD"]:::repo
        SchoolYearCRUD["SchoolYear CRUD"]:::repo
    end

    %% ORM Layer
    subgraph "ORM Layer"
        subgraph "Session & Base\n(app/db)"
            Session["Session Factory\n(session.py)"]:::data
            BaseClass["Declarative Base\n(base.py, base_class.py)"]:::data
        end
        subgraph "Models\n(app/models)"
            MStudent["Student Model"]:::data
            MSubject["Subject Model"]:::data
            MGrade["Grade Model"]:::data
            MGradeSubject["Grade-Subject Model"]:::data
            MNationality["Nationality Model"]:::data
            MRegistration["Registration Model"]:::data
            MSchoolYear["SchoolYear Model"]:::data
        end
    end

    %% Database & Migrations
    DB["PostgreSQL Database"]:::infra
    subgraph "Migrations\n(Alembic)"
        AlembicConf["alembic.ini"]:::infra
        AlembicDir["alembic/ (versions)"]:::infra
    end

    %% Flows
    Clients --> Main
    Main --> API
    API --> API
    API --> StudentRouter
    API --> SubjectRouter
    API --> GradeRouter
    API --> NationalityRouter
    API --> RegistrationRouter
    API --> SchoolYearRouter
    StudentRouter --> Deps
    SubjectRouter --> Deps
    GradeRouter --> Deps
    NationalityRouter --> Deps
    RegistrationRouter --> Deps
    SchoolYearRouter --> Deps
    StudentRouter --> StudentSchema
    SubjectRouter --> SubjectSchema
    GradeRouter --> GradeSchema
    GradeRouter --> GradeSubjectSchema
    NationalityRouter --> NationalitySchema
    RegistrationRouter --> RegistrationSchema
    SchoolYearRouter --> SchoolYearSchema
    StudentRouter --> StudentCRUD
    SubjectRouter --> SubjectCRUD
    GradeRouter --> GradeCRUD
    GradeRouter --> GradeSubjectCRUD
    NationalityRouter --> NationalityCRUD
    RegistrationRouter --> RegistrationCRUD
    SchoolYearRouter --> SchoolYearCRUD
    Deps --> Session
    StudentCRUD --> Session
    SubjectCRUD --> Session
    GradeCRUD --> Session
    GradeSubjectCRUD --> Session
    NationalityCRUD --> Session
    RegistrationCRUD --> Session
    SchoolYearCRUD --> Session
    StudentCRUD --> MStudent
    SubjectCRUD --> MSubject
    GradeCRUD --> MGrade
    GradeSubjectCRUD --> MGradeSubject
    NationalityCRUD --> MNationality
    RegistrationCRUD --> MRegistration
    SchoolYearCRUD --> MSchoolYear
    Session --> DB
    AlembicConf --> MStudent
    AlembicConf --> DB
    AlembicDir --> MSubject
    AlembicDir --> DB

    %% Click Events
    click Main "https://github.com/7s9n/small_sms_api/blob/master/app/main.py"
    click API "https://github.com/7s9n/small_sms_api/blob/master/app/api/api_v1/api.py"
    click StudentRouter "https://github.com/7s9n/small_sms_api/blob/master/app/api/api_v1/routes/student.py"
    click SubjectRouter "https://github.com/7s9n/small_sms_api/blob/master/app/api/api_v1/routes/subject.py"
    click GradeRouter "https://github.com/7s9n/small_sms_api/blob/master/app/api/api_v1/routes/grade.py"
    click NationalityRouter "https://github.com/7s9n/small_sms_api/blob/master/app/api/api_v1/routes/nationality.py"
    click RegistrationRouter "https://github.com/7s9n/small_sms_api/blob/master/app/api/api_v1/routes/registration.py"
    click SchoolYearRouter "https://github.com/7s9n/small_sms_api/blob/master/app/api/api_v1/routes/school_year.py"
    click Deps "https://github.com/7s9n/small_sms_api/blob/master/app/deps.py"
    click Config "https://github.com/7s9n/small_sms_api/blob/master/app/core/config.py"
    click BaseCRUD "https://github.com/7s9n/small_sms_api/blob/master/app/crud/base.py"
    click StudentCRUD "https://github.com/7s9n/small_sms_api/blob/master/app/crud/crud_student.py"
    click SubjectCRUD "https://github.com/7s9n/small_sms_api/blob/master/app/crud/crud_subject.py"
    click GradeCRUD "https://github.com/7s9n/small_sms_api/blob/master/app/crud/crud_grade.py"
    click GradeSubjectCRUD "https://github.com/7s9n/small_sms_api/blob/master/app/crud/crud_grade_subject.py"
    click NationalityCRUD "https://github.com/7s9n/small_sms_api/blob/master/app/crud/crud_nationality.py"
    click RegistrationCRUD "https://github.com/7s9n/small_sms_api/blob/master/app/crud/crud_registration.py"
    click SchoolYearCRUD "https://github.com/7s9n/small_sms_api/blob/master/app/crud/crud_school_year.py"
    click Session "https://github.com/7s9n/small_sms_api/blob/master/app/db/session.py"
    click BaseClass "https://github.com/7s9n/small_sms_api/blob/master/app/db/base.py"
    click MStudent "https://github.com/7s9n/small_sms_api/blob/master/app/models/student.py"
    click MSubject "https://github.com/7s9n/small_sms_api/blob/master/app/models/subject.py"
    click MGrade "https://github.com/7s9n/small_sms_api/blob/master/app/models/grade.py"
    click MGradeSubject "https://github.com/7s9n/small_sms_api/blob/master/app/models/grade_subject.py"
    click MNationality "https://github.com/7s9n/small_sms_api/blob/master/app/models/nationality.py"
    click MRegistration "https://github.com/7s9n/small_sms_api/blob/master/app/models/registration.py"
    click MSchoolYear "https://github.com/7s9n/small_sms_api/blob/master/app/models/school_year.py"
    click StudentSchema "https://github.com/7s9n/small_sms_api/blob/master/app/schemas/student.py"
    click SubjectSchema "https://github.com/7s9n/small_sms_api/blob/master/app/schemas/subject.py"
    click GradeSchema "https://github.com/7s9n/small_sms_api/blob/master/app/schemas/grade.py"
    click GradeSubjectSchema "https://github.com/7s9n/small_sms_api/blob/master/app/schemas/grade_subject.py"
    click NationalitySchema "https://github.com/7s9n/small_sms_api/blob/master/app/schemas/nationality.py"
    click RegistrationSchema "https://github.com/7s9n/small_sms_api/blob/master/app/schemas/registration.py"
    click SchoolYearSchema "https://github.com/7s9n/small_sms_api/blob/master/app/schemas/school_year.py"
    click AlembicConf "https://github.com/7s9n/small_sms_api/blob/master/alembic.ini"
    click AlembicDir "https://github.com/7s9n/small_sms_api/tree/master/alembic/"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000;
    classDef api fill:#90EE90,stroke:#000;
    classDef repo fill:#FFFF99,stroke:#000;
    classDef data fill:#FFA500,stroke:#000;
    classDef infra fill:#FF6347,stroke:#000;
```
