# dixichain/okaz-backend architecture

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

- Interactive diagram: https://gitdiagram.com/dixichain/okaz-backend
- Repository: https://github.com/dixichain/okaz-backend

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Browser / API Client"]:::client

    %% ASGI Server Entry
    Uvicorn["Uvicorn ASGI Server"]:::server

    %% FastAPI Application Container
    subgraph "FastAPI Application"
        direction TB
        FastAPIApp["FastAPI app.main"]:::server
        subgraph "Routers"
            direction TB
            DealsRouter["/deals Router"]:::component
            PartiesRouter["/parties Router"]:::component
            ReportsRouter["/reports Router"]:::component
            HealthRouter["/health Router"]:::component
        end
        Schemas["Pydantic Schemas"]:::schemas
        Models["SQLAlchemy Models"]:::component
        DBSession["DB Session (SQLAlchemy)"]:::component
    end

    %% External Services
    DB[(PostgreSQL Database)]:::database

    %% Configuration & Documentation
    subgraph "Config & Docs"
        direction TB
        Env[".env.example"]:::config
        Requirements["requirements.txt"]:::config
        Runtime["runtime.txt"]:::config
        Readme["README.md"]:::docs
    end

    %% Data Flows
    Client -->|"HTTPS (CORS)"| Uvicorn
    Uvicorn -->|"ASGI handoff"| FastAPIApp
    FastAPIApp -->|"router dispatch"| DealsRouter
    FastAPIApp -->|"router dispatch"| PartiesRouter
    FastAPIApp -->|"router dispatch"| ReportsRouter
    FastAPIApp -->|"router dispatch"| HealthRouter
    DealsRouter -->|"Validate/Serialize"| Schemas
    PartiesRouter -->|"Validate/Serialize"| Schemas
    ReportsRouter -->|"Validate/Serialize"| Schemas
    HealthRouter -->|"liveness/readiness"| Schemas
    DealsRouter -->|"use session"| DBSession
    PartiesRouter -->|"use session"| DBSession
    ReportsRouter -->|"use session"| DBSession
    DBSession -->|"SQL"| DB
    DB -->|"rows"| DBSession
    DBSession -->|"data objects"| Models
    Models -->|"ORM mapping"| DBSession
    FastAPIApp --> Env
    FastAPIApp --> Requirements
    FastAPIApp --> Runtime
    FastAPIApp --> Readme

    %% Click Events
    click FastAPIApp "https://github.com/dixichain/okaz-backend/blob/main/app/main.py"
    click Uvicorn "https://github.com/dixichain/okaz-backend/blob/main/runtime.txt"
    click DBSession "https://github.com/dixichain/okaz-backend/blob/main/app/db.py"
    click Models "https://github.com/dixichain/okaz-backend/blob/main/app/models.py"
    click Schemas "https://github.com/dixichain/okaz-backend/blob/main/app/schemas.py"
    click DealsRouter "https://github.com/dixichain/okaz-backend/blob/main/app/routers/deals.py"
    click PartiesRouter "https://github.com/dixichain/okaz-backend/blob/main/app/routers/parties.py"
    click ReportsRouter "https://github.com/dixichain/okaz-backend/blob/main/app/routers/reports.py"
    click HealthRouter "https://github.com/dixichain/okaz-backend/blob/main/app/routers/health.py"
    click Env "https://github.com/dixichain/okaz-backend/blob/main/.env.example"
    click Requirements "https://github.com/dixichain/okaz-backend/blob/main/requirements.txt"
    click Runtime "https://github.com/dixichain/okaz-backend/blob/main/runtime.txt"
    click Readme "https://github.com/dixichain/okaz-backend/blob/main/README.md"

    %% Styles
    classDef client fill:#E8F1FF,stroke:#3B82F6,color:#1E40AF;
    classDef server fill:#FFF4E5,stroke:#F59E0B,color:#B45309;
    classDef component fill:#ECFDF5,stroke:#10B981,color:#065F46;
    classDef schemas fill:#FEF3C7,stroke:#D97706,color:#92400E;
    classDef database fill:#F3F4F6,stroke:#6B7280,color:#374151;
    classDef config fill:#F0F9FF,stroke:#0284C7,color:#065F46;
    classDef docs fill:#F5F3FF,stroke:#7C3AED,color:#4C1D95;
```
