Overview¶

A high-level summary of all API modules, available endpoints, and their responsibilities.

Modules¶

Core¶

The app/core/ package contains shared infrastructure used by all feature modules:

Configuration — Application settings
Metadata — App name, version, OpenAPI info
Logging — Structured logging setup
Exceptions — Domain exception classes
Exception Handlers — Global error handling
Middlewares — CORS configuration
Telemetry — OpenTelemetry tracing

Feature Modules¶

User¶

The app/modules/user/ package provides user management:

Models — Database table (SQLModel)
Schemas — Request/Response shapes (Pydantic)
Repository — Database CRUD operations
Service — Business logic
Routes — FastAPI endpoints

Endpoints¶

Base URL¶

http://localhost:8000/api/v1

User Endpoints¶

Method	Endpoint	Description	Status
`POST`	`/api/v1/users/`	Create user	201
`GET`	`/api/v1/users/`	List users	200
`GET`	`/api/v1/users/{id}`	Get user by ID	200
`PATCH`	`/api/v1/users/{id}`	Update user	200
`DELETE`	`/api/v1/users/{id}`	Delete user	204

System Endpoints (Root Level)¶

Method	Endpoint	Description	Status
`GET`	`/health`	Health check	200
`GET`	`/ready`	Readiness probe	200

Interactive Docs¶

Available in non-production environments:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

Module Index¶

Module	Description	Reference
`app.core.config`	Application settings	Core
`app.core.exceptions`	Domain exceptions	Core
`app.modules.user.models`	User database model	User
`app.modules.user.schemas`	User API schemas	User
`app.modules.user.service`	User business logic	User
`app.modules.user.routes`	User endpoints	User

Usage Examples¶

Create a User¶

import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "http://localhost:8000/api/v1/users/",
        json={"email": "user@example.com", "full_name": "John Doe"},
    )
    user = response.json()

List Users¶

async with httpx.AsyncClient() as client:
    response = await client.get("http://localhost:8000/api/v1/users/")
    users = response.json()