QuoinAPI¶

The architectural cornerstone for high-performance, scalable Python services.

QuoinAPI (pronounced "koyn") is a high-performance, scalable foundation designed to serve as the structural cornerstone for modern Python backends. Built with FastAPI, SQLModel, and the Astral stack (uv, ruff, ty), it provides a battle-tested "Golden Path" for developers who prioritize architectural integrity, type safety, and observability.

Key Highlights¶

High-Performance Core¶

• Async-first patterns with FastAPI and async PostgreSQL via asyncpg
• Lightning-fast tooling powered by uv for dependency management
• Optimized for production workloads with connection pooling

Structural Integrity¶

• 100% type-annotated code verified by ty and strict linting via ruff
• Domain-driven design with module-level exceptions and rich error context
• API versioning with /api/v1/ prefix for future-proof evolution

Built-in Observability¶

• Integrated OpenTelemetry for distributed tracing
• Structured logging with Structlog for machine-readable logs
• Health checks and readiness endpoints out of the box

Architectural Efficiency¶

• Ready-to-use template that eliminates boilerplate
• Environment-based configuration with .env file selection
• Just-based automation for common development tasks

Tech Stack & Tools¶

• Framework: FastAPI
• Database: PostgreSQL (using asyncpg driver)
• ORM: SQLModel (SQLAlchemy wrapper)
• Migrations: Alembic
• Package Manager: uv (Fast Python package installer)
• Task Runner: just
• Linting/Formatting: Ruff
• Type Checking: ty (Static type checker)
• Testing: Pytest, pytest-cov
• Observability: OpenTelemetry, Structlog
• Documentation: Zensical (MkDocs Material)

Learn more about our technology choices and decision log →

Quick Start¶

# 1. Clone the repository and configure environment
git clone https://github.com/balakmran/quoin-api.git
cd quoin-api
cp .env.example .env

# 2. Setup project (install dependencies & pre-commit hooks)
just setup

# 3. Start DB, apply migrations, and run the server
just dev

Visit the API documentation at http://localhost:8000/docs.

Need help? Check out the Getting Started Guide →

Running Application¶

The application home page provides real-time health indicators and quick links to API documentation.

️Architecture¶

graph TB
    Client[Client/Browser] -->|HTTP| FastAPI[FastAPI Application]
    FastAPI -->|Business Logic| Service[Service Layer]
    Service -->|Database Access| Repository[Repository Layer]
    Repository -->|SQL| PostgreSQL[(PostgreSQL)]

    FastAPI -->|Structured Logs| Structlog[Structlog]
    FastAPI -->|Traces| OTEL[OpenTelemetry]

    Service -->|Domain Exceptions| Handlers[Exception Handlers]
    Handlers -->|JSON Response| Client

Read the full architecture documentation →

Project Structure¶

├── app/
│   ├── core/
│   │   ├── config.py             # Pydantic settings
│   │   ├── exception_handlers.py # Global exception handlers
│   │   ├── exceptions.py         # Custom exceptions
│   │   ├── logging.py            # Structlog configuration
│   │   ├── metadata.py           # Application metadata
│   │   ├── middlewares.py        # Middleware configuration
│   │   ├── openapi.py            # OpenAPI configuration
│   │   ├── schemas.py            # Pydantic schemas
│   │   ├── security.py           # Security utilities
│   │   └── telemetry.py          # OpenTelemetry instrumentation
│   ├── db/                       # Database connection & base models
│   │   ├── base.py               # Base models
│   │   └── session.py            # Database session
│   ├── modules/
│   │   ├── system/               # System health & status
│   │   └── user/                 # User management module
│   │       ├── exceptions.py     # Domain-specific exceptions
│   │       ├── models.py         # SQLModel database tables
│   │       ├── schemas.py        # Pydantic request/response models
│   │       ├── repository.py     # Database access (CRUD)
│   │       ├── service.py        # Business logic
│   │       └── routes.py         # FastAPI router endpoints
│   ├── static/                   # Static assets
│   ├── templates/                # Jinja2 templates
│   │   └── index.html            # Home page
│   ├── api.py                    # API Route structure
│   └── main.py                   # Application entry point
├── tests/                        # Pytest test suite
├── alembic/                      # Database migrations
├── docs/                         # This documentation
├── scripts/                      # Utility scripts
├── .env.example                  # Environment variables template
├── docker-compose.yml            # Local dev environment
├── Dockerfile                    # Production Docker image
├── AGENTS.md                     # AI Agent instructions
├── justfile                      # Task runner
└── pyproject.toml                # Dependencies & config

Documentation¶

Roadmap¶

See the Roadmap for planned features and upcoming milestones.

Contributing¶

We welcome contributions! Please read our Contributing Guide to learn about our development process, coding standards, and how to submit pull requests.

License¶

This project is licensed under the MIT License. See the LICENSE for details.