How mead-team/oknawa-backend-server works
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)