# mead-team/oknawa-backend-server architecture

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

- Interactive diagram: https://gitdiagram.com/mead-team/oknawa-backend-server
- Repository: https://github.com/mead-team/oknawa-backend-server

## Overview

##### Project type and purpose
- This “Ok, Nawa Backend Server” is a full-stack (primarily backend) location-based REST API service written in Python 3.11+, containerized with Docker Compose. It serves static UI assets (index.html, main.css) and exposes HTTP endpoints for managing “location” resources, persisting data in a relational database (via SQLAlchemy/Alembic), and running scheduled background tasks.

##### File structure
- Top-level:
- Dockerfile / docker-compose.yml: container definitions for the API service and database.
- alembic.ini + migrations/: DB migration configurations & scripts.
- app/: the primary FastAPI application, subdivided into core, crud, models, routers, schemas, services.
- tests/: pytest suites for API endpoints and CRUD logic.
- app/core/: application bootstrap (settings, DB engine, middleware, logging, scheduler, static file routing).
- app/models + app/schemas: domain model definitions (SQLAlchemy) and Pydantic request/response schemas.
- app/crud + app/services + app/routers: layered structure—routers handle HTTP, services encapsulate business logic, CRUD layer accesses the DB via SQLAlchemy.
- Supporting utilities under app/core/util: e.g. external distance-calculation, OpenAPI helper.

##### README for additional insights
- Confirms Docker Compose usage, Python 3.11 requirement, describes versioning.

a. Main components
- Client (browser or other HTTP client)
- Docker Compose network staging two containers:
– Backend Service (FastAPI app)
– Database (e.g., PostgreSQL)
- Within the Backend Service container:
– API Gateway / FastAPI server (uvicorn)
– Static file handler (serving index.html, CSS)
– Middleware layer (logging, request/response hooks)
– Router layer (app/routers)
– Service layer (app/services)
– CRUD / Repository layer (app/crud)
– Database engine & session (configured in app/core/database.py)
– Scheduler (app/core/scheduler.py) for background tasks
– Util modules for external API calls (distance, OpenAPI)
b. Relationships & interactions
- Client → HTTP(S) request → FastAPI → Router → Service → CRUD → Database.
- Database responses propagate back up: CRUD → Service → Router → Response → Client.
- Scheduler triggers periodic jobs that run business-logic services and DB operations.
- Static content served directly from FastAPI’s static middleware.
- External calls from util modules plug into Service layer as needed.
c. Architectural patterns/design principles
- Layered (presentation, business, data) architecture.
- Dependency Injection (FastAPI’s Depends for settings, DB sessions).
- Separation of concerns: routers vs. services vs. crud vs. models/schemas.
- Containerization: each service/component in its own Docker container, networked via Docker Compose.
d. Key technologies/frameworks
- FastAPI + Uvicorn (web framework & server)
- SQLAlchemy & Alembic (ORM & migrations)
- Pydantic (data validation)
- Docker & Docker Compose (deployment)
- Pytest (testing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External client
    Client["Client (Browser/HTTP)"]:::external

    %% Docker Compose services
    subgraph "Docker Compose Network"
        direction TB
        subgraph "fastapi-app (Backend Service)" 
            direction TB
            APIGateway["FastAPI Server\n(app/main.py)"]:::compute
            StaticServer["Static File Handler\n(app/core/static/)"]:::compute
            Middleware["Middleware Layer\n(app/core/middleware.py)"]:::compute
            Settings["Settings & DI\n(app/core/setting.py\napp/core/dependency.py)"]:::config
            DBConfig["DB Engine & Session\n(app/core/database.py)"]:::config
            Logging["Logging Config\n(app/core/logging.py)"]:::config
            Metadata["Core Metadata\n(app/core/metadata.py)"]:::config
            Scheduler["Scheduler (Background Tasks)\n(app/core/scheduler.py)"]:::background

            subgraph "Utility Modules" 
                direction TB
                AiohttpUtil["aiohttp_util.py"]:::external
                DistanceCalc["distance_calculator.py"]:::external
                OpenAPIUtil["open_api.py"]:::external
                RouteUtil["route_util.py"]:::external
            end

            subgraph "Layered Application"
                direction TB
                Routers["Router Layer\n(app/routers/location.py)"]:::compute
                Services["Service Layer\n(app/services/location.py)"]:::compute
                CRUD["CRUD Layer\n(app/crud/location.py)"]:::compute
                Models["Domain Models\n(base.py\nlocation.py)"]:::compute
                Schemas["Pydantic Schemas\n(base.py\nreq/location.py\nres/location.py)"]:::compute
            end
        end

        subgraph "postgres-db (Database Service)"
            DB["PostgreSQL\n(port 5432)"]:::storage
        end
    end

    %% Migrations
    Alembic["Alembic Migrations\n(alembic.ini\nmigrations/)"]:::config

    %% Connections
    Client -->|"HTTP Request"| APIGateway
    APIGateway --> StaticServer
    APIGateway --> Middleware
    Middleware --> Routers
    Routers --> Services
    Services --> CRUD
    CRUD --> DBConfig
    DBConfig --> DB
    Scheduler --> Services
    Services --> AiohttpUtil
    Services --> DistanceCalc
    Services --> OpenAPIUtil
    Services --> RouteUtil
    Alembic --> DB

    %% Click Events
    click APIGateway "https://github.com/mead-team/oknawa-backend-server/blob/main/app/main.py"
    click StaticServer "https://github.com/mead-team/oknawa-backend-server/tree/main/app/core/static/"
    click Middleware "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/middleware.py"
    click Settings "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/setting.py"
    click Settings "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/dependency.py"
    click DBConfig "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/database.py"
    click Scheduler "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/scheduler.py"
    click Logging "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/logging.py"
    click Metadata "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/metadata.py"
    click AiohttpUtil "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/util/aiohttp_util.py"
    click DistanceCalc "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/util/distance_calculator.py"
    click OpenAPIUtil "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/util/open_api.py"
    click RouteUtil "https://github.com/mead-team/oknawa-backend-server/blob/main/app/core/util/route_util.py"
    click CRUD "https://github.com/mead-team/oknawa-backend-server/blob/main/app/crud/location.py"
    click Models "https://github.com/mead-team/oknawa-backend-server/blob/main/app/models/base.py"
    click Models "https://github.com/mead-team/oknawa-backend-server/blob/main/app/models/location.py"
    click Schemas "https://github.com/mead-team/oknawa-backend-server/blob/main/app/schemas/base.py"
    click Schemas "https://github.com/mead-team/oknawa-backend-server/blob/main/app/schemas/req/location.py"
    click Schemas "https://github.com/mead-team/oknawa-backend-server/blob/main/app/schemas/res/location.py"
    click Routers "https://github.com/mead-team/oknawa-backend-server/blob/main/app/routers/location.py"
    click Services "https://github.com/mead-team/oknawa-backend-server/blob/main/app/services/location.py"
    click Alembic "https://github.com/mead-team/oknawa-backend-server/blob/main/alembic.ini"
    click Alembic "https://github.com/mead-team/oknawa-backend-server/blob/main/migrations/env.py"
    click Alembic "https://github.com/mead-team/oknawa-backend-server/blob/main/migrations/script.py.mako"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef storage fill:#E6F4EA,stroke:#1b6d3c,color:#1b6d3c
    classDef external fill:#FFF4E5,stroke:#d9822b,color:#d9822b
    classDef background fill:#F0F0F0,stroke:#836042,color:#836042
    classDef config fill:#F5F5F5,stroke:#888888,color:#444444
```
