# pandaind/movie-api architecture

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

- Interactive diagram: https://gitdiagram.com/pandaind/movie-api
- Repository: https://github.com/pandaind/movie-api

## Overview

##### Project type and purpose
- This is a full-stack Python microservice exposing multiple interfaces (REST, WebSocket chat, GraphQL, gRPC) built with FastAPI.
- It supports user and movie management, real-time chat, ML utilities, background jobs, and rich security (API keys, GitHub OAuth, MFA). Data is persisted in PostgreSQL with Alembic migrations.

##### File structure
- Top-level: configuration (pyproject.toml, Dockerfile, docker-compose.yml, alembic.ini), entry scripts (start.py, main.py, grpc_server.py).
- app/api: REST endpoints
- app/chat: WebSocket chat management
- app/gql: GraphQL helpers
- app/grpc: gRPC API and response models
- app/services: business logic
- app/models & app/db: SQLAlchemy ORM & DB connection
- app/security: authentication/authorization
- app/jobs: background scheduler tasks
- app/ml: machine-learning helpers
- app/middleware: request/response/CORS/HTTPS redirect handlers
- templates: Jinja2 HTML for chat and login
- tests: unit and integration tests

##### Key insights from README
- Supports Docker and Docker-Compose for local deployment with a Postgres container.
- Alembic migrations for schema evolution.
- gRPC proto files generate grpcserver_pb2(.py) and grpcserver_pb2_grpc(.py).
- Suggests Gunicorn+Uvicorn for production, HTTPS redirect middleware.

a. Main components
- Clients: HTTP clients (e.g., web browser, curl), WebSocket clients, GraphQL clients, gRPC clients
- API Gateway Layer (FastAPI instance)
– REST controllers (app/api/v1)
– WebSocket manager (app/chat)
– GraphQL endpoint (app/gql)
– gRPC server (grpc_server.py + app/grpc)
- Middleware & Cross-cutting Concerns
– Security (API Key, OAuth, MFA)
– Rate limiting, internationalization, logging
– HTTP↔HTTPS redirect, CORS
- Service Layer (app/services, app/ml)
- Data Layer
– ORM models (app/models)
– Database connector (app/db/database.py, PostgreSQL)
– Migrations (Alembic)
- Background Scheduler (app/jobs)
- External Services
– GitHub OAuth
- Infrastructure
– Docker & Docker-Compose
– Gunicorn + Uvicorn worker

b. Relationships & interactions
1. Client → FastAPI HTTP/S
- Request passes through ASGI middleware (CORS, rate-limit, security)
- Routed to REST controllers or GraphQL resolver
- Controllers call Service Layer → ORM → Postgres
- Response flows back through middlewares.
2. WebSocket Client → WebSocket Manager → chat_room & secure_chat_room → Service → Data Layer
3. gRPC Client → grpc_server endpoint → app/grpc/api.py → Services → Data Layer
4. Scheduler jobs invoke Service Layer on a timed basis
5. ML module invoked by controllers or scheduled jobs
6. External GitHub OAuth calls for login flow

c. Architectural patterns & design principles
- Layered Architecture: Presentation (controllers), Business (services), Data (ORM & DB)
- Dependency Injection via FastAPI’s parameter system
- Modular separation: REST vs WebSocket vs GraphQL vs gRPC
- Single source of truth for config (app/core/config.py)
- Asynchronous I/O (async/await in FastAPI, WebSockets, gRPC)
- SQL migrations with Alembic

d. Key technologies & libraries
- FastAPI, Uvicorn, Gunicorn
- SQLAlchemy, Alembic, PostgreSQL
- python‐grpc, grpcio, protobuf
- Jinja2 templates for chat pages
- APScheduler or built-in scheduler for jobs
- python‐dotenv, Pydantic for settings
- Pre-commit, Black, isort for code quality

##### Final advice
- Every module package as part of a larger layer rather than individual files.
- Protocols (HTTP/1.1, WebSocket, gRPC).
- This level of detail will guide engineering and stakeholders alike to understand component responsibilities, data flows, and deployment topology.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Clients" 
        direction TB
        HTTP["HTTP Client"]:::external
        WSClient["WebSocket Client"]:::external
        GraphQLClient["GraphQL Client"]:::external
        gRPCClient["gRPC Client"]:::external
    end

    subgraph "API Gateway" 
        direction TB
        subgraph "REST API" 
            REST["REST Controllers"]:::entry
        end
        subgraph "WebSocket API" 
            WS["WebSocket Manager"]:::entry
        end
        subgraph "GraphQL API"
            GQL["GraphQL Helpers"]:::entry
        end
        subgraph "gRPC API"
            GRPCScript["grpc_server.py"]:::entry
            GRPCPkg["gRPC Handlers"]:::entry
        end
    end

    subgraph "Middleware & Security"
        direction TB
        Middle["Middleware Layer"]:::middleware
        Security["Security Layer"]:::middleware
    end

    subgraph "Service Layer"
        direction TB
        Services["Business Services"]:::service
        ML["ML Utilities"]:::service
    end

    subgraph "Data Layer"
        direction TB
        Models["ORM Models"]:::data
        DB["Database Connector"]:::data
    end

    Migrations["Alembic Migrations"]:::migrations
    Scheduler["Background Scheduler"]:::service
    ExternalGitHub["GitHub OAuth"]:::external
    subgraph "Infrastructure"
        direction TB
        Entry["Entry Scripts"]:::infra
        DockerfileNode["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
    end

    %% Connections
    HTTP --> Middle
    WSClient --> Middle
    GraphQLClient --> Middle
    gRPCClient --> Middle

    Middle --> Security
    Security --> REST
    Security --> WS
    Security --> GQL
    Security --> GRPCScript

    REST --> Services
    WS --> Services
    GQL --> Services
    GRPCScript --> Services
    GRPCPkg --> Services

    Services --> Models
    Models --> DB
    Services --> ML
    Scheduler --> Services
    Migrations --> DB
    ExternalGitHub --> Security

    %% Infra connections
    Entry --> REST
    Entry --> GRPCScript
    Compose --> DB
    Compose --> Entry

    %% Click Events
    click REST "https://github.com/pandaind/movie-api/tree/master/app/api/v1"
    click WS "https://github.com/pandaind/movie-api/tree/master/app/chat"
    click GQL "https://github.com/pandaind/movie-api/blob/master/app/gql/gql_utils.py"
    click GRPCScript "https://github.com/pandaind/movie-api/blob/master/grpc_server.py"
    click GRPCPkg "https://github.com/pandaind/movie-api/blob/master/app/grpc/api.py"
    click Middle "https://github.com/pandaind/movie-api/tree/master/app/middleware"
    click Security "https://github.com/pandaind/movie-api/tree/master/app/security"
    click Services "https://github.com/pandaind/movie-api/tree/master/app/services"
    click ML "https://github.com/pandaind/movie-api/tree/master/app/ml"
    click Models "https://github.com/pandaind/movie-api/tree/master/app/models"
    click DB "https://github.com/pandaind/movie-api/blob/master/app/db/database.py"
    click Migrations "https://github.com/pandaind/movie-api/tree/master/alembic/"
    click Scheduler "https://github.com/pandaind/movie-api/blob/master/app/jobs/scheduler_jobs.py"
    click Entry "https://github.com/pandaind/movie-api/blob/master/start.py"
    click DockerfileNode "https://github.com/pandaind/movie-api/tree/master/Dockerfile"
    click Compose "https://github.com/pandaind/movie-api/blob/master/docker-compose.yml"

    %% Styles
    classDef entry fill:#cce5ff,stroke:#004085,color:#004085
    classDef service fill:#d4edda,stroke:#155724,color:#155724
    classDef data fill:#fff3cd,stroke:#856404,color:#856404
    classDef migrations fill:#ffeeba,stroke:#856404,color:#856404
    classDef middleware fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#6c757d
    classDef infra fill:#d6d8d9,stroke:#343a40,color:#343a40
```
