Modular async web application framework built on FastAPI, SQLAlchemy, and Redis.
A scaffold for building backend services with:
- Engine registry — pluggable business-logic units with dependency-ordered lifecycle (start/stop/health)
- Module registry — declarative data model tracking for auto-discovery
- Dependency injection — FastAPI
Depends()for clean testing withoutmock.patch - Async-first — SQLAlchemy asyncio, asyncpg, uvicorn
# Install
uv sync
# Run tests
uv run pytest
# Run dev server
uv run uvicorn skeleton.app:create_app --factory --reload
# Lint + format + type-check
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src/skeleton/
├── src/skeleton/ # Application source
│ ├── api/ # FastAPI routers and response schemas
│ │ ├── schemas.py # Pydantic response models
│ │ └── v1/ # Versioned API (health, registry endpoints)
│ ├── app.py # Application factory + lifespan
│ ├── config.py # Settings (pydantic-settings, env vars)
│ ├── database.py # Async SQLAlchemy engine + session helpers
│ ├── deps.py # FastAPI DI providers
│ ├── exceptions.py # Custom exception hierarchy
│ └── registry.py # Engine + module registries
├── tests/ # pytest test suite
├── migrations/ # Alembic async migrations
├── docs/ # Architecture + development + deployment guides
├── pyproject.toml # Single source of truth (deps, tools, config)
└── AGENTS.md # AI agent operating manual
See docs/reference/architecture.md for the registry pattern, engine lifecycle, and module system.
See docs/guides/development.md for setup, testing, linting, and migration workflow.
See docs/guides/versioning.md for SemVer, git tagging, conventional commits, and release process.
- RBAC Module — Role-Based Access Control with CRUDS capabilities (Users, Groups, Roles, Capabilities)
See docs/guides/deployment.md for Docker builds, env vars, and production config.
This project is licensed under the GNU General Public License v3.0.