hatchback 0.3.0

The high-performance, drift-ready boilerplate for FastAPI.

Hatchback is a powerful CLI tool designed to bootstrap and manage production-ready FastAPI applications. It comes pre-loaded with best practices, security hardening, and a modular architecture that scales.

✨ Features

• 🚀 Production Ready: SQLAlchemy 2.0, Pydantic v2, and Alembic pre-configured.
• 🛡️ Secure by Default: Rate limiting (SlowAPI), hardened Auth (JWT), secure secret generation, and non-root Docker containers.
• ⚡ Blazing Fast: Optional uv support for lightning-fast dependency management.
• 🏗️ Clean Architecture: Service-Repository pattern for maintainable code.
• ✅ Testing Ready: Integrated pytest setup with hbk test.
• 🐳 Dockerized: Ready-to-deploy docker-compose setup with healthchecks.
• 🤖 AI-Powered: Built-in Agent Skills for GitHub Copilot and VS Code agent mode.
• 🧩 Modular: Grow projects with hbk add <module> — install integrations like Stripe or Docker into an existing project, no re-init.
• 💳 Stripe Integration (opt-in): Checkout sessions, signed webhooks, and plans, subscriptions & payments tables wired into your DB.
• 🏎️ Drift Mode: A CLI that drives as good as it looks.

📦 Installation

pip install hatchback

Tip: Use hbk as a shortcut for hatchback — all commands work with either. For example, hbk make product is equivalent to hatchback make product.

🏁 Quick Start

1. Initialize a new project

hbk init my_project_name

You will be prompted for:

• Database Name
• Docker inclusion
• uv usage (if installed, for faster setup)
• Stripe integration (opt-in)

Options:

• --use-uv: Force usage of uv for virtualenv creation.
• --no-docker: Skip Docker file generation.
• --stripe / --no-stripe: Include or skip the Stripe payment stack.

2. Start the Engine

Before hitting the gas, ensure your database is running and the schema is initialized.

1. Start Database:

cd my_project_name
docker-compose up -d db

(Or configure a local Postgres instance in .env)

2. Initialize Database: Create and apply the first migration for the built-in models (User, Tenant).

hbk migrate create -m "initial_setup"
hbk migrate apply

3. Run Server: Start the development server with hot-reloading.

hbk run

🎉 Success! Your API is now live.

• API Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

3. Scaffold Resources

Don't write boilerplate. Generate Models, Schemas, Repositories, Services, and Routes in one go. Hatchback automatically registers your new routes and services, so they are ready to use immediately.

hbk make product

4. Remove Resources

Changed your mind? Remove a scaffolded resource and clean up all imports automatically.

hbk remove product          # asks for confirmation
hbk remove product --force  # skips confirmation

5. Manage Migrations

Wrapper around Alembic to keep your database in sync.

# Create a migration
hbk migrate create -m "add products table"

# Apply migrations
hbk migrate apply

# Rollback the last migration
hbk migrate downgrade

# Rollback multiple steps
hbk migrate downgrade -r -2

# Rollback everything
hbk migrate downgrade -r base

6. Seed Data

Populate your database with initial data (default tenant and admin user).

hbk seed

7. Import Existing Database

Have an existing database? Hatchback can inspect it and generate your entire project architecture automatically.

# Output models only to a file
hbk inspect --url postgresql://user:pass@localhost:5432/mydb --output app/models/legacy.py

# Full Scaffold Mode (Recommended)
# Generates Models, Services, Repositories, Schemas, and Routes for every table
hbk inspect --scaffold --url postgresql://user:pass@localhost:5432/mydb

8. Upgrade Existing Projects

After upgrading Hatchback, sync the latest agent skills and infrastructure files into your project.

pip install --upgrade hatchback
hbk upgrade

This syncs new files (like agent skills) without touching your Docker config, user code, or environment files.

9. Run Tests

Hatchback projects come with pytest configured.

hbk test

🏗️ Architecture Explained

Hatchback follows a Service-Repository pattern to keep your code modular and testable.

1. Routes (app/routes/): Handle HTTP requests/responses and dependency injection. They delegate business logic to Services.
2. Services (app/services/): Contain the business logic. They orchestrate data operations using Repositories.
3. Repositories (app/repositories/): Handle direct database interactions (CRUD). They abstract the SQL/ORM details from the rest of the app.
4. Models (app/models/): SQLAlchemy database definitions.
5. Schemas (app/schemas/): Pydantic validation and serialization schemas.

🤖 Agent Skills

Hatchback projects ship with built-in Agent Skills in .github/skills/:

• hatchback — Full project overview, CLI commands, database config, auth system, and conventions.
• clean-architecture — Layered architecture rules, code examples, anti-patterns, and testing patterns.
• stripe — (only when initialized with --stripe) Stripe conventions: required metadata, webhook events, the Plan / Subscription / Payment models, and required env vars.

These help AI coding assistants (GitHub Copilot, VS Code agent mode) understand your project structure and follow established patterns automatically.

💳 Stripe Integration (opt-in)

Enable Stripe at init time or add it later to an existing project — it ships as an optional module:

hbk init my_project --stripe   # at init time
hbk add stripe                  # or later, in an existing project

This adds:

• stripe to requirements.txt
• STRIPE_API_KEY and STRIPE_WEBHOOK_SECRET to .env / .env.example
• app/services/payment.py — PaymentService wrapping the Stripe SDK + persistence helpers
• app/routes/payment.py — endpoints:
  • GET /payments/plans — list active plans
  • GET /payments/subscriptions/me — current tenant's subscriptions
  • GET /payments/me — current tenant's payments
  • POST /payments/checkout-session — create a Stripe Checkout Session (auto-tags tenant_id & user_id in metadata)
  • POST /payments/webhook — verified Stripe webhook receiver (persists events)
• app/models/{plan,subscription,payment}.py + matching repositories
• Three new tables on the next migration: plans, subscriptions, payments

After init, set your keys in .env and run:

hbk migrate create -m "add stripe tables"
hbk migrate apply

Webhook events persisted: checkout.session.completed, payment_intent.succeeded|payment_failed|canceled, and customer.subscription.created|updated|deleted. They are linked back to your tenant via the tenant_id metadata that the checkout endpoint sets automatically.

🧩 Optional Modules (hbk add)

Hatchback ships integrations as opt-in modules so you can grow a project after init without re-bootstrapping it.

hbk add --list        # see what's available
hbk add stripe        # add Stripe to an existing project
hbk add docker        # add Dockerfile + docker-compose.yml
hbk remove stripe     # uninstall (same command as for scaffolded resources; auto-detected)

Every module is described by a module.json manifest and the installer takes care of:

• copying files into the project
• appending pip packages to requirements.txt (encoding-preserving: utf-8 / utf-8-sig / utf-16)
• adding env vars to .env and .env.example (only the missing ones)
• registering routes in app/routes/__init__.py
• registering models / repositories / services in their __init__.py
• recording the install in .hatchback/modules.json so hbk remove can cleanly undo it

Current modules: stripe, docker. See ROADMAP.md for what's next.

📂 Project Structure

my_project/
├── .github/
│   └── skills/       # Agent Skills for AI assistants
├── app/
│   ├── config/       # Database, Security, Limiter config
│   ├── models/       # SQLAlchemy Database Models
│   ├── schemas/      # Pydantic Data Schemas
│   ├── repositories/ # Data Access Layer (CRUD)
│   ├── services/     # Business Logic
│   ├── routes/       # API Endpoints
│   ├── dependencies.py
│   └── main.py
├── alembic/          # Database Migrations
├── tests/            # Pytest Suite
├── docker-compose.yml
└── requirements.txt

🛡️ Security Features

• Rate Limiting: Built-in protection against brute-force attacks.
• Secure Headers: Trusted host middleware configuration.
• Password Hashing: Argon2/Bcrypt support via Passlib.
• Docker Security: Runs as a non-root user to prevent container breakout.

🔧 CLI Reference

Command	Description
hbk init <name>	Initialize a new project (add --stripe for payments)
hbk add <module>	Install an optional module into the current project (e.g.stripe, docker)
hbk add --list	List available optional modules
hbk run	Start dev server with hot-reload
hbk make <resource>	Scaffold a new resource
hbk remove <resource|module>	Remove a scaffolded resource or uninstall a module (auto-detected)
hbk migrate create -m "msg"	Create a new Alembic migration
hbk migrate apply	Apply pending migrations
hbk migrate downgrade	Rollback last migration (-r -2 for multiple)
hbk seed	Seed database with initial data
hbk inspect --url <db_url>	Inspect existing DB and generate models
hbk upgrade	Sync latest skills and infra files
hbk test	Run the test suite

🗺️ Roadmap

Track upcoming features and the catalogue of optional modules (Stripe✓, Docker✓, OAuth, S3, Celery, Sentry and more) in ROADMAP.md. Contributions welcome — every module is a good first PR.

---

Built with 💖 and 🏎️ by Ignacio Bares(nachovoss) and the Hatchback Team.

Support

Hatchback is an open-source project. If you'd like to support the development, you can donate via Bitcoin:

BTC Address: \bc1q9fznxyf0skq8ux5ysrggw3veuqf92xtr25cccq\

Thank you for your support!