{"id":50886532,"url":"https://github.com/balakmran/quoin-api","last_synced_at":"2026-06-15T17:32:19.700Z","repository":{"id":337311410,"uuid":"1105074662","full_name":"balakmran/quoin-api","owner":"balakmran","description":"QuoinAPI: The Foundation for your Python backend API","archived":false,"fork":false,"pushed_at":"2026-06-05T05:40:43.000Z","size":16577,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T07:33:22.215Z","etag":null,"topics":["astral-ty","docker","fastapi","postgresql","pydantic-v2","pytest","pytest-cov","python","rest-api","ruff","sqlmodel","uv","zensical"],"latest_commit_sha":null,"homepage":"https://balakmran.github.io/quoin-api/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/balakmran.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-27T05:17:35.000Z","updated_at":"2026-06-05T06:39:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/balakmran/quoin-api","commit_stats":null,"previous_names":["balakmran/fastapi-backend","balakmran/quoin-api"],"tags_count":8,"template":true,"template_full_name":null,"purl":"pkg:github/balakmran/quoin-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balakmran%2Fquoin-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balakmran%2Fquoin-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balakmran%2Fquoin-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balakmran%2Fquoin-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/balakmran","download_url":"https://codeload.github.com/balakmran/quoin-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balakmran%2Fquoin-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34374146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astral-ty","docker","fastapi","postgresql","pydantic-v2","pytest","pytest-cov","python","rest-api","ruff","sqlmodel","uv","zensical"],"created_at":"2026-06-15T17:32:17.808Z","updated_at":"2026-06-15T17:32:19.686Z","avatar_url":"https://github.com/balakmran.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QuoinAPI\n\n[![CI](https://github.com/balakmran/quoin-api/actions/workflows/ci.yml/badge.svg)](https://github.com/balakmran/quoin-api/actions/workflows/ci.yml)\n[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.136.3-teal.svg)](https://fastapi.tiangolo.com/)\n[![SQLModel](https://img.shields.io/badge/SQLModel-0.0.38-blue.svg)](https://sqlmodel.tiangolo.com/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**The architectural cornerstone for high-performance, scalable Python services.**\n\n![QuoinAPI](docs/assets/images/quoin-api-banner.png)\n\nQuoinAPI (pronounced \"koyn\") is a high-performance, scalable foundation\ndesigned to serve as the structural cornerstone for modern Python backends.\nBuilt with FastAPI, SQLModel, and the Astral stack (uv, ruff, ty), it provides\na battle-tested \"Golden Path\" for developers who prioritize architectural\nintegrity, type safety, and observability.\n\n## Key Highlights\n\n### High-Performance Core\n\n- **Async-first** patterns with FastAPI and async PostgreSQL via `asyncpg`\n- **Lightning-fast tooling** powered by `uv` for dependency management\n- **Optimized** for production workloads with connection pooling\n\n### Structural Integrity\n\n- **100% type-annotated** code verified by `ty` and strict linting via `ruff`\n- **Domain-driven design** with module-level exceptions and rich error context\n- **API versioning** with `/api/v1/` prefix for future-proof evolution\n\n### Built-in Observability\n\n- **Integrated OpenTelemetry** for distributed tracing\n- **Structured logging** with Structlog for machine-readable logs\n- **Health checks** and readiness endpoints out of the box\n\n### Architectural Efficiency\n\n- **Ready-to-use template** that eliminates boilerplate\n- **Environment-based configuration** with `.env` file selection\n- **Just-based automation** for common development tasks\n\n## Tech Stack\n\n- **Framework:** FastAPI\n- **Database:** PostgreSQL (using `asyncpg` driver)\n- **ORM:** SQLModel (SQLAlchemy wrapper)\n- **Migrations:** Alembic\n- **Package Manager:** `uv` (Fast Python package installer)\n- **Task Runner:** `just`\n- **Linting/Formatting:** Ruff\n- **Type Checking:** ty (Static type checker)\n- **Testing:** Pytest, pytest-cov\n- **Observability:** OpenTelemetry, Structlog\n- **Documentation:** Zensical (MkDocs Material)\n\n## Use as a Template\n\nQuoinAPI is designed to be used as a project generator via [Copier](https://copier.readthedocs.io/). To create a new API project using this architecture, first install Copier:\n\n```bash\nuv tool install copier\n# OR\npipx install copier\n```\n\nThen generate your project:\n\n```bash\ncopier copy https://github.com/balakmran/quoin-api.git my-awesome-api --trust\n```\n\nCopier will prompt you for your project name, database prefixes, and other configuration variables.\n\n## Quick Start\n\n```bash\n# 1. Clone the repository and configure environment\ngit clone https://github.com/balakmran/quoin-api.git\ncd quoin-api\ncp .env.example .env\n\n# 2. Setup project (install dependencies \u0026 pre-commit hooks)\njust setup\n\n# 3. Start DB, apply migrations, and run the server\njust dev\n```\n\nVisit the API documentation at\n[http://localhost:8000/docs](http://localhost:8000/docs).\n\n## Project Structure\n\n```plaintext\n├── app/\n│   ├── core/\n│   │   ├── config.py             # Pydantic settings\n│   │   ├── exceptions.py         # Custom exceptions\n│   │   ├── exception_handlers.py # Global exception handlers\n│   │   ├── logging.py            # Structlog configuration\n│   │   ├── metadata.py           # Application metadata\n│   │   ├── middlewares.py        # Middleware configuration\n│   │   ├── openapi.py            # OpenAPI metadata \u0026 config\n│   │   └── telemetry.py          # OpenTelemetry instrumentation\n│   ├── db/                       # Database connection \u0026 base models\n│   │   ├── session.py            # Database session\n│   │   └── base.py               # Base models\n│   ├── modules/\n│   │   └── user/                 # Example domain module\n│   │       ├── exceptions.py     # Domain-specific exceptions\n│   │       ├── models.py         # SQLModel database tables\n│   │       ├── schemas.py        # Pydantic request/response models\n│   │       ├── repository.py     # Database access (CRUD)\n│   │       ├── service.py        # Business logic\n│   │       └── routes.py         # FastAPI router endpoints\n│   ├── static/                   # Static assets (css, img)\n│   ├── templates/                # Jinja2 templates\n│   │   └── index.html            # Home page\n│   ├── api.py                    # API Route structure\n│   └── main.py                   # App entry point\n├── tests/                        # Pytest suite\n├── alembic/                      # Database migrations\n├── docs/                         # Documentation\n├── .env.example                  # Environment variables template\n├── docker-compose.yml            # Local dev environment\n├── Dockerfile                    # Production Docker image\n├── CLAUDE.md                     # AI agent instructions\n├── justfile                      # Command runner\n├── pyproject.toml                # Dependencies \u0026 config\n└── zensical.toml                 # Documentation config\n```\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n## AI-Assisted Development\n\nThis project has a Claude Code setup with project-specific skills,\nquality-enforcement hooks, and live SDK documentation via MCP.\nSee the [AI-Assisted Development guide](docs/guides/ai-setup.md) for\nthe full reference.\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for planned features and upcoming milestones.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this\nproject.\n\n## License\n\nThis project is licensed under the terms of the [MIT license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalakmran%2Fquoin-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbalakmran%2Fquoin-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalakmran%2Fquoin-api/lists"}