# sxxrya666/movies-api architecture

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

- Interactive diagram: https://gitdiagram.com/sxxrya666/movies-api
- Repository: https://github.com/sxxrya666/movies-api

## Overview

##### Project type and purpose
- This is a Python-based RESTful backend service (likely built with FastAPI) that provides user authentication and movie-rating endpoints.
- There’s no separate frontend—clients (mobile/web) consume JSON APIs exposed by this service.
- Alembic is used for database migrations; JWT utilities for auth; SQLAlchemy (db/models.py) for the ORM layer.

##### File structure
- Top level:
– main.py: app entry point, mounts routers
– pyproject.toml: project metadata & dependencies
– .env.example: environment variables template
- configs/: holds key management (e.g. JWT secrets)
- routers/: two REST endpoint groups
– auth.py: login/signup, token generation
– movie_rating.py: CRUD on movie ratings
- utils/: pure-function modules for JWT encode/decode
- db/: SQLAlchemy setup (db.py) and models.py
- alembic/: migration config and version scripts
- misc/: docs/notes (not part of runtime)
- uv.lock / .gitignore / .vscode: tooling and environment

##### Readme insights
- (Empty)—all architectural cues come from file structure.

a. Main components
1. Client (Browser/Mobile/CLI)
2. ASGI Server (Uvicorn/Gunicorn)
3. FastAPI App
– Routers layer: auth router, movie_rating router
– Utils layer: JWT encode/decode
– Config loader: keys.py (.env)
4. Database layer
– SQLAlchemy ORM (db/db.py & models.py)
– Postgres (or similar SQL DB)
5. Migration tool
– Alembic (env.py, versions)
b. Relationships & interactions
- Client → ASGI Server: HTTP requests (JSON)
- ASGI Server → FastAPI App: request lifecycle
- FastAPI App → Routers: route matching
- Routers → Utils (for token ops)
- Routers → DB layer: CRUD operations
- DB layer ↔ Database: SQL queries
- Migration tool (offline) ↔ Database: schema changes
c. Architectural patterns/design principles
– Layered architecture: Presentation (HTTP) → Business (routers+utils) → Data (ORM+DB)
– Modular separation: routers handle endpoints, utils handle pure functions, configs isolated, db models separate.
– Configuration via environment (.env + configs/keys.py)
– Migrations side-loaded via Alembic, decoupled from runtime.
d. Key technologies
- FastAPI (HTTP framework)
- Uvicorn (ASGI server)
- SQLAlchemy (ORM)
- Alembic (migrations)
- PyJWT / custom utils (JWT handling)
- Postgres or any SQL DB

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "External Actor"
        Client["Client (Browser/Mobile/CLI)"]
    end

    %% Runtime Components
    Client -->|"HTTP Request"| ASGI["ASGI Server\n(Uvicorn/Gunicorn)"]:::runtime
    ASGI -->|"request lifecycle"| App["FastAPI App"]:::runtime

    subgraph "FastAPI Application"
        AuthRouter["Auth Router\n(/auth endpoints)"]:::runtime
        MovieRouter["MovieRating Router\n(/movie_ratings endpoints)"]:::runtime
        App --> AuthRouter
        App --> MovieRouter
    end

    %% Utilities and Config
    subgraph "Utilities & Configuration"
        GenToken["gen_access_tkn.py"]:::utils
        DecodeToken["decode_jwt.py"]:::utils
        EnvFile[".env.example"]:::config
        KeysConfig["configs/keys.py"]:::config
    end
    click GenToken "https://github.com/sxxrya666/movies-api/blob/master/utils/gen_access_tkn.py"
    click DecodeToken "https://github.com/sxxrya666/movies-api/blob/master/utils/decode_jwt.py"
    click EnvFile "https://github.com/sxxrya666/movies-api/blob/master/.env.example"
    click KeysConfig "https://github.com/sxxrya666/movies-api/blob/master/configs/keys.py"

    AuthRouter --> GenToken
    AuthRouter --> DecodeToken
    MovieRouter --> GenToken
    MovieRouter --> DecodeToken
    KeysConfig --> App

    %% ORM Layer
    subgraph "ORM & Database Access"
        DBSetup["db/db.py"]:::runtime
        Models["db/models.py"]:::runtime
    end
    click DBSetup "https://github.com/sxxrya666/movies-api/blob/master/db/db.py"
    click Models "https://github.com/sxxrya666/movies-api/blob/master/db/models.py"

    AuthRouter --> DBSetup
    MovieRouter --> DBSetup
    DBSetup --> Models

    Models -->|"SQL Queries"| Database[(Database)]:::database

    %% Migrations
    subgraph "Migration Tool (Alembic)"
        AlembicEnv["alembic/env.py"]:::migration
        AlembicIni["alembic.ini"]:::migration
        AlembicVersions["alembic/versions/"]:::migration
    end
    click AlembicEnv "https://github.com/sxxrya666/movies-api/blob/master/alembic/env.py"
    click AlembicIni "https://github.com/sxxrya666/movies-api/blob/master/alembic.ini"
    click AlembicVersions "https://github.com/sxxrya666/movies-api/tree/master/alembic/versions/"

    AlembicEnv -.->|"schema changes"| Database
    AlembicVersions -.-> Database

    %% Legend
    subgraph "Legend"
        LR1["Runtime Components"]:::runtime
        LR2["External Services"]:::database
        LR3["Utilities & Config"]:::utils
        LR4["Migration Tool"]:::migration
    end

    classDef runtime fill:#E0F7FA,stroke:#006064,color:#004D40;
    classDef database fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32;
    classDef utils fill:#FFF3E0,stroke:#E65100,color:#BF360C;
    classDef config fill:#FFFDE7,stroke:#F9A825,color:#F57F17;
    classDef migration fill:#ECEFF1,stroke:#607D8B,color:#37474F;
```
