Backcraft

Enterprise-grade FastAPI project generator with AI-powered business logic injection.

Backcraft turns a project description — a natural-language prompt, an interactive wizard, or a canvas file — into a complete, working FastAPI backend: SQLAlchemy models with real relationships, Alembic migrations, JWT authentication, CRUD routes, tests, Docker/Kubernetes manifests, and optional integrations (Stripe payments, Celery task queues, Prometheus/Grafana monitoring). With AI business logic injection enabled (the default), Claude fills in real validation rules, workflows, and domain logic instead of leaving # TODO stubs.

Requirements

• Python 3.9+
• An Anthropic API key for AI-powered generation (fullauto, chat, and business logic injection). Not required for generate with --no-ai or use_business_logic=False.

Installation

pip install backcraft-engine

Or from source:

git clone <this-repository>
cd backcraft-backend
uv sync

Quickstart

Set your Anthropic API key once (stored in ~/.backcraft/credentials, never in a project directory):

backcraft auth

Then generate a project from a one-line description:

backcraft fullauto "A task management API where users can create projects and tasks, with JWT authentication"

Backcraft analyzes the description, designs entities and relationships, shows you a summary, and (after confirmation) generates the full project into ./generated/<app-name>/.

Other ways to build a project

# Step-by-step interactive wizard (terminal UI)
backcraft builder

# Same wizard, with a browser-based visual canvas (Next.js + React Flow)
backcraft builder --web

# Conversational, multi-turn chat instead of a single prompt
backcraft chat

# Generate directly from an existing canvas file (JSON/YAML)
backcraft generate --canvas my_project.json

# Validate a canvas file or an existing generated project
backcraft validate ./my_project

Run backcraft --help or backcraft <command> --help for the full option list.

What gets generated

• Models & migrations: SQLAlchemy 2.0 models (Mapped/mapped_column), with real relationship()/ForeignKey wiring for one-to-many, many-to-one, and many-to-many relationships, plus Alembic migrations.
• API: FastAPI routes and Pydantic schemas per entity, JWT authentication, health checks, rate limiting, and (optionally) OAuth2/API-key auth.
• Tests: pytest suites (unit, integration, e2e) generated alongside the app.
• Infrastructure: Dockerfile, docker-compose (dev/prod), GitHub Actions and GitLab CI pipelines, nginx config, deploy/backup scripts.
• Optional integrations, enabled per-project via the canvas:
  • Stripe checkout sessions + webhook handling
  • Celery task queue (worker + beat, with a docker-compose service each)
  • Prometheus metrics endpoint + scrape config, Grafana dashboard with provisioning
  • Kubernetes manifests (Deployment, Service, Ingress, ConfigMap, Secret, HPA)

Configuration

Generated projects read their configuration from a .env file (see the generated .env.example). Backcraft itself only needs ANTHROPIC_API_KEY, which backcraft auth manages for you:

backcraft auth            # prompt for and store a key
backcraft auth --status   # check whether a key is configured
backcraft auth --clear    # remove the stored key

Development

uv sync --extra dev

# Run the fast test suite (no API key required)
pytest tests/ -m "not slow and not requires_llm"

# Run the full suite, including the AI-powered generation tests
# (requires ANTHROPIC_API_KEY, calls the real Anthropic API, and is slow)
pytest tests/ -m "requires_llm"

# Lint and format
ruff check src/ && black src/ && isort src/

License

MIT — see LICENSE.