# april202305/bye--distract-backend architecture

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

- Interactive diagram: https://gitdiagram.com/april202305/bye--distract-backend
- Repository: https://github.com/april202305/bye--distract-backend

## Overview

##### Project Type and Purpose
- This is a backend‐only, RESTful API service for managing Pomodoro timer sessions, tasks, and user profiles.
- Built with FastAPI, it exposes endpoints for timer control, task CRUD operations, and user authentication/management.

##### File Structure
- Top-level:
- alembic.ini, migrations/ → database migration setup (Alembic).
- app/ → main application package.
- requirements.txt → dependency list.
- Under app/:
- api/ → route definitions (one file per resource: users.py, tasks.py, video.py, etc.).
- services/ → business logic layer (auth.py, task operations, video utilities).
- database/ → SQLAlchemy engine and session setup (database.py).
- models/ → ORM models (models.py).
- schemas/ → Pydantic request/response models (login_schemas.py, task.py, etc.).
- utilts/ → video input/output helpers.
- main.py → FastAPI app instantiation, router inclusion, middleware, startup events.

##### README for Additional Insights
- Tech Stack: FastAPI, SQLAlchemy, Alembic, JWT, Swagger UI.
- Key features: timer management (start/pause/stop), task tracking, user register/login, session history.
- Endpoints listed for timers (/timer/*), tasks (/tasks), and users (/users/*).

a. Main Components
1. Client (Web or Mobile UI)
2. FastAPI App (app/main.py)
3. API Routers (app/api/*.py)
4. Service Layer (app/services/*.py)
5. Schema Layer (app/schemas) for validation
6. Database Layer:
- SQLAlchemy ORM (app/models/models.py)
- Database session/engine (app/database/database.py)
- Alembic migrations (migrations/)
7. Authentication: JWT token generator/validator (in services/auth.py)
8. External Interfaces:
- Swagger UI / ReDoc
- (Optional) Object storage for user_photo or video processing modules
b. Relationships and Interactions
- Client sends HTTP request → FastAPI entry point (main.py)
- Router matches path → Pydantic schema validates input
- Router calls service function → business logic applies rules/auth
- Service uses SQLAlchemy session → issues CRUD queries to PostgreSQL
- Service returns domain models → routers convert to response schemas
- FastAPI serializes and returns JSON response
- Alembic handles schema migrations offline or at startup
- JWT auth: middleware or dependency injection protects certain endpoints
c. Architectural Patterns
- Layered Architecture (Controller → Service → Repository/ORM → Database)
- Dependency Injection (FastAPI dependencies)
- Repository/Unit of Work implicitly via SQLAlchemy sessions
- Migrations as versioned schema management
d. Key Technologies/Frameworks
- FastAPI for HTTP layer
- Pydantic for data validation
- SQLAlchemy ORM for persistence
- Alembic for migrations
- PyJWT (or fastapi-jwt) for auth
- Uvicorn as ASGI server

##### Key Details to Capture
- All major endpoints (timer, tasks, users).
- Separation of concerns: validation (schemas), business logic (services), data access (models + database).
- Migration workflow and DB schema evolution.
- Authentication mechanism and protected route handling.
- External API documentation endpoints (Swagger UI).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Client["Client (Web/Mobile)"]:::external
    Swagger["Swagger UI / ReDoc"]:::external

    %% FastAPI Application Entry Point
    FastAPIApp["FastAPI App\n(app/main.py)"]:::controller

    %% API Layer
    subgraph "API Routers (app/api)" 
        direction TB
        TimerRouter["TimerRouter\n(~/sta.py)"]:::controller
        StudyRouter["StudyRoomRouter\n(~/study_room.py)"]:::controller
        TaskRouter["TaskRouter\n(~/tasks.py)"]:::controller
        UserPhotoRouter["UserPhotoRouter\n(~/user_photo.py)"]:::controller
        UserRouter["UserRouter\n(~/users.py)"]:::controller
        VideoRouter["VideoRouter\n(~/video.py)"]:::controller
    end

    %% Service Layer
    subgraph "Services (app/services)" 
        direction TB
        AuthService["AuthService\n(app/services/auth.py)"]:::service
    end

    %% Schema Layer
    subgraph "Schemas (app/schemas)" 
        direction TB
        LoginSchema["LoginSchemas\n(app/schemas/login_schemas.py)"]:::schema
        TaskSchema["TaskSchemas\n(app/schemas/task.py)"]:::schema
        StaSchema["StatisticsSchemas\n(app/schemas/sta.py)"]:::schema
        StudySchema["StudyRoomSchemas\n(app/schemas/study_room.py)"]:::schema
    end

    %% Data Layer
    subgraph "Database Layer"
        direction TB
        DBSession["DB Session & Engine\n(app/database/database.py)"]:::database
        ORMModels["ORM Models\n(app/models/models.py)"]:::database
        DB["PostgreSQL DB"]:::database
    end

    %% Migration Subsystem
    subgraph "Migrations"
        direction TB
        AlembicConfig["Alembic Config\n(alembic.ini)"]:::migration
        MigrationDir["Migration Scripts\n(migrations/)"]:::migration
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        VideoIn["Video Input Helper\n(app/utilts/video_in.py)"]:::util
        VideoOut["Video Output Helper\n(app/utilts/video_out.py)"]:::util
        OSSExample["OSS Config Example\n(app/oss_config.example.py)"]:::util
        OSSConfig["Global OSS Config\n(oss_config.py)"]:::util
    end

    %% Flow
    Client --> FastAPIApp
    Swagger --> FastAPIApp
    FastAPIApp --> TimerRouter
    FastAPIApp --> StudyRouter
    FastAPIApp --> TaskRouter
    FastAPIApp --> UserPhotoRouter
    FastAPIApp --> UserRouter
    FastAPIApp --> VideoRouter

    TimerRouter -->|"validates using"| LoginSchema
    TaskRouter -->|"validates using"| TaskSchema
    TimerRouter -->|"validates using"| StaSchema
    StudyRouter -->|"validates using"| StudySchema
    UserRouter -->|"auth dependency"| AuthService
    TaskRouter --> AuthService
    VideoRouter --> VideoIn
    VideoRouter --> VideoOut

    TimerRouter --> AuthService
    StudyRouter --> AuthService

    TimerRouter --> DBSession
    TaskRouter --> DBSession
    UserRouter --> DBSession
    VideoRouter --> DBSession
    StudyRouter --> DBSession

    AuthService --> DBSession
    DBSession --> ORMModels
    ORMModels --> DB

    DBSession --> MigrationDir
    AlembicConfig --> MigrationDir

    %% Click Events
    click FastAPIApp "https://github.com/april202305/bye--distract-backend/blob/main/app/main.py"
    click TimerRouter "https://github.com/april202305/bye--distract-backend/blob/main/app/api/sta.py"
    click StudyRouter "https://github.com/april202305/bye--distract-backend/blob/main/app/api/study_room.py"
    click TaskRouter "https://github.com/april202305/bye--distract-backend/blob/main/app/api/tasks.py"
    click UserPhotoRouter "https://github.com/april202305/bye--distract-backend/blob/main/app/api/user_photo.py"
    click UserRouter "https://github.com/april202305/bye--distract-backend/blob/main/app/api/users.py"
    click VideoRouter "https://github.com/april202305/bye--distract-backend/blob/main/app/api/video.py"
    click AuthService "https://github.com/april202305/bye--distract-backend/blob/main/app/services/auth.py"
    click DBSession "https://github.com/april202305/bye--distract-backend/blob/main/app/database/database.py"
    click ORMModels "https://github.com/april202305/bye--distract-backend/blob/main/app/models/models.py"
    click LoginSchema "https://github.com/april202305/bye--distract-backend/blob/main/app/schemas/login_schemas.py"
    click TaskSchema "https://github.com/april202305/bye--distract-backend/blob/main/app/schemas/task.py"
    click StaSchema "https://github.com/april202305/bye--distract-backend/blob/main/app/schemas/sta.py"
    click StudySchema "https://github.com/april202305/bye--distract-backend/blob/main/app/schemas/study_room.py"
    click AlembicConfig "https://github.com/april202305/bye--distract-backend/blob/main/alembic.ini"
    click MigrationDir "https://github.com/april202305/bye--distract-backend/tree/main/migrations/"
    click VideoIn "https://github.com/april202305/bye--distract-backend/blob/main/app/utilts/video_in.py"
    click VideoOut "https://github.com/april202305/bye--distract-backend/blob/main/app/utilts/video_out.py"
    click OSSExample "https://github.com/april202305/bye--distract-backend/blob/main/app/oss_config.example.py"
    click OSSConfig "https://github.com/april202305/bye--distract-backend/blob/main/oss_config.py"

    %% Styles
    classDef external fill:#DAD2E9,stroke:#957DAD,color:#000
    classDef controller fill:#D0E6FF,stroke:#69A1FF,color:#000
    classDef service fill:#D6F5D6,stroke:#3EBF3E,color:#000
    classDef schema fill:#F0F0F0,stroke:#B0B0B0,color:#000
    classDef database fill:#FFE0B2,stroke:#FFB74D,color:#000
    classDef migration fill:#FFF9C4,stroke:#FBC02D,color:#000
    classDef util fill:#E0F7FA,stroke:#4DD0E1,color:#000
```
