How dixichain/okaz-backend works
Project type and purpose
• This is a monolithic backend service (a proof-of-concept) implemented in Python using FastAPI.
• It exposes REST endpoints for "deals", "parties", "reports", and a health-check, and persists data in a PostgreSQL database.
File structure
• app/main.py: application bootstrap (FastAPI instance, CORS, router registration, runner via Uvicorn)
• app/db.py: database connection+session management using SQLAlchemy (DATABASE_URL)
• app/models.py: ORM models mapped to PostgreSQL tables
• app/schemas.py: Pydantic request/response schemas (DTOs)
• app/routers/*.py: modular “controller” layers for each route group:
– deals.py (CRUD for deals)
– parties.py (CRUD for parties)
– reports.py (data aggregation or reporting endpoints)
– health.py (liveness/readiness probe)
• requirements.txt/runtime.txt/.env.example: runtime and environment config
README for additional insights
• Confirms Python 3.11+, FastAPI + Uvicorn, PostgreSQL, CORS with FRONTEND_ORIGIN
• Deployment on Render (build & start commands, required env vars)
• Database schema must be preloaded and CSV data imported beforehand
Components and relationships
a. Main Components
– Clients (e.g., Frontend single-page app at FRONTEND_ORIGIN)
– FastAPI App (Uvicorn process hosting app.main:app)
• Routers: /deals, /parties, /reports, /health
• Service Layer: business logic (could be inline in routers or factored out)
• Data Layer: SQLAlchemy session from app/db.py
– PostgreSQL Database instance (external managed service)
b. Interactions/Data Flow
1) Client (browser or API client) issues HTTPS requests (CORS enforced) →
2) Uvicorn + FastAPI picks up the request →
3) Router dispatch to appropriate endpoint function →
4) Schemas validate incoming payload →
5) Endpoint calls SQLAlchemy session to query/update DB →
6) DB returns rows →
7) Endpoint serializes response via Pydantic schemas → HTTP response back to client
c. Architectural patterns/design principles
– Layered architecture:
• Presentation: FastAPI routers
• Validation/DTO: Pydantic schemas
• Persistence: SQLAlchemy models + session
– Single-process monolith, no microservices
– Twelve-factor apt: environment variables for config, separate build & run phases
d. Key technologies
– FastAPI (web framework)
– Uvicorn (ASGI server)
– SQLAlchemy (ORM)
– PostgreSQL (relational datastore)
– Pydantic (validation & serialization)
– Render.com (deployment)
Detail is key
• Call out the uvicorn server as the process entry point
• Where environment variables feed into the system at startup
• CORS enforcement between FRONTEND_ORIGIN and the API