How pandaind/movie-api works
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.