---

Quick start

uv tool install forge-scaffolder
forge new my-api
cd my-api
uv sync

Run and migration commands depend on the resolved stack. Forge prints them after generation, and the generated project README repeats the ones that apply.

Or skip installation for a one-off run:

uvx --from forge-scaffolder forge new my-api

Role	Name
PyPI package	forge-scaffolder
CLI command	forge
Repository	Lacky227/forge-cli

---

What Forge is

Starting a backend project means deciding framework, project structure, persistence, migrations, Docker, testing, and linting — often from scratch, every time.

Forge turns those explicit decisions into a coherent, runnable project. It resolves implications (ORM, clients, dependencies, commands) and generates a codebase you can install, run, and keep developing by hand. Optional project modules (Products, Categories, Files, Background Jobs, Email, Webhooks, Authentication, Authorization) add real capabilities — see docs/modules.md.

It is a scaffolder, not a runtime dependency of the projects it creates.

---

Interactive experience

$ forge new my-api

What are you building?
> REST API

Language
> Python

Framework
> FastAPI

Architecture
> Modular Monolith

Add a database?
> Yes

Database type
> Both

SQL database
> PostgreSQL

Include Alembic migrations?
> Yes

NoSQL database
> Redis

Include Docker support?
> Yes

Include testing setup (pytest)?
> Yes

Include Ruff linting?
> Yes

✓ Created my-api

Location:
  ./my-api

Stack:
  FastAPI
  Modular Monolith
  PostgreSQL
  SQLAlchemy
  Alembic
  Redis
  redis

Next steps:
  cd my-api
  uv sync
  docker compose up -d db redis
  ...

Prompts adapt to the stack. Django, for example, always asks for SQL and offers NoSQL as an optional addition — it never asks for SQLAlchemy or Alembic.

---

Supported stack

Python REST API generation for FastAPI, Django, and Flask.

	Simple	Modular Monolith	Clean Architecture
FastAPI	✓	✓	✓
Django	✓	✓	✓
Flask	✓	✓	✓

Capability	Options	Resolved into
SQL	PostgreSQL, SQLite	FastAPI/Flask → SQLAlchemy (+ optional Alembic); Django → Django ORM + migrations
NoSQL	MongoDB, Redis	MongoDB → PyMongo; Redis → redis-py
Tooling	pytest, Ruff, Docker, optional GitHub Actions CI	Wired when selected

---

Persistence

SQL and NoSQL are independent first-class choices:

Persistence
├── SQL
│   ├── PostgreSQL
│   └── SQLite
│
└── NoSQL
    ├── MongoDB
    └── Redis

Choose none, SQL only, NoSQL only, or both (at most one engine from each category).

Django note: Django REST APIs always require SQL. MongoDB or Redis can be added alongside it as separate clients — not as Django ORM backends.

Project modules

Optional multi-select modules add real application capabilities:

Module	Requires / implies
Products	SQL
Categories	SQL
Files	SQL + local or S3-compatible storage (optional MinIO with Docker)
Background Jobs	RQ + Redis
Email	SMTP
Webhooks	Background Jobs → RQ + Redis (outgoing delivery only)
Authentication	SQL; Alembic on FastAPI/Flask
Authorization	Authentication + SQL; reusable RBAC and policies

When Products and Categories are both selected, products may reference a category. Collection CRUD endpoints include pagination, filtering, and allow-listed sorting. Details: docs/modules.md.

---

Generated project

Example: FastAPI · Modular Monolith · PostgreSQL · Redis · Alembic · Docker

my-api/
├── alembic.ini
├── docker-compose.yml
├── Dockerfile
├── .env.example
├── pyproject.toml
├── README.md
├── migrations/
├── src/
│   └── my_api/
│       ├── main.py
│       ├── api/
│       │   └── routes/
│       ├── core/
│       │   ├── config.py
│       │   ├── database.py
│       │   └── redis_client.py
│       ├── models/
│       ├── repositories/
│       ├── schemas/
│       └── services/
└── tests/
    └── test_health.py

Generated projects are conventional Python packages — installable with uv, runnable immediately, and editable without Forge.

---

Architecture styles

Style	Best for
Simple	Small APIs and prototypes that prefer minimal structure
Modular Monolith	Growing applications organized around features/modules
Clean Architecture	Projects that need explicit boundaries and dependency direction

Architecture chooses layout. Framework chooses how HTTP and persistence are wired. The same three styles work across FastAPI, Django, and Flask.

---

Presets

Presets are named compositions of valid Forge choices — not separate generators. They still go through the same resolution pipeline.

Preset	Stack
fastapi-auth	FastAPI · Modular Monolith · Authentication · PostgreSQL · Alembic · Docker
django-auth	Django · Modular Monolith · Authentication + Authorization · PostgreSQL · Docker
fastapi-postgres	FastAPI · Modular Monolith · PostgreSQL · Alembic · Docker
fastapi-postgres-clean	FastAPI · Clean Architecture · PostgreSQL · Alembic · Docker
fastapi-mongo	FastAPI · Modular Monolith · MongoDB · Docker
fastapi-catalog	FastAPI · Modular Monolith · Products + Categories · PostgreSQL · Alembic · Docker
fastapi-files	FastAPI · Simple · Files (local storage) · SQLite · Alembic
flask-postgres	Flask · Modular Monolith · PostgreSQL · Alembic · Docker
django-postgres	Django · Modular Monolith · PostgreSQL · Docker

forge new my-api --preset fastapi-postgres
forge new my-api --preset fastapi-postgres --dry-run
forge plan --preset fastapi-mongo

---

Inspect before you generate

forge plan resolves a configuration and prints the full GenerationPlan — without writing any files. forge new --dry-run answers a different question: which concrete files would be created at the destination.

forge plan --preset fastapi-mongo
forge new my-api --preset fastapi-postgres --dry-run

Project
  Framework:     FastAPI
  Architecture:  Modular Monolith

NoSQL
  Database:      MongoDB
  Client:        pymongo

Tooling
  Testing:       pytest
  Linting:       Ruff
  Docker:        yes

Use it to verify implied ORM/clients, dependencies, and commands before scaffolding.

---

YAML configuration

Fully non-interactive generation for scripts and CI:

name: my-api
type: rest-api
framework: fastapi
architecture: modular-monolith

persistence:
  sql: postgresql
  nosql: redis

modules:
  - products
  - categories
  - files
  - background-jobs
  - email
  - webhooks
  - authentication
  - authorization

authentication:
  registration: true
  email_verification: true
  password_reset: true

storage:
  backend: s3
  minio: true

migrations: true
testing: true
linting: true
docker: true

forge new --config forge.yaml

Omit modules (or use modules: []) for a scaffold-only project. storage is only valid when Files is selected; authentication options are valid whenever Authentication is selected or implied. Authorization implies Authentication. Verification/reset imply Email, but Background Jobs and Redis remain optional. Authentication requires SQL and, on FastAPI/Flask, Alembic. Legacy database: postgresql remains supported as an SQL-only shorthand; prefer persistence for new configs.

--preset and --config cannot be combined.

---

Philosophy

• Working software first — selected integrations are wired, not stubbed.
• Explicit resolution — Forge shows what it inferred (ORM, migrations, clients).
• Proportional architecture — no layers or dependencies you did not ask for.
• Owned code — output should look like a normal project a team would maintain.
• Scaffolder, not a framework — Forge leaves the generated tree; it is not a runtime.

---

Documentation

Document	Contents
docs/product.md	Product definition, principles, scope
docs/architecture.md	Resolution model, frameworks, layouts
docs/cli.md	Commands, presets, YAML schema
docs/generation.md	Compatibility matrix and quality bar
docs/development.md	Toolchain, packaging, versioning
CHANGELOG.md	Release notes

---

Project status

Current development version: 0.5.0 — public development / alpha.

Current limitations:

• Other languages and non-REST project types are not generated yet
• Django REST APIs require SQL (NoSQL alone is not enough)
• Redis integration is a client wiring — not cache/session/queue abstractions
• MongoDB uses PyMongo directly — no ODM layer
• At most one SQL database and one NoSQL database per project
• MFA, passkeys/OAuth, audit platforms, cookie sessions, and automatic Products/Categories/Files protection remain future work
• Access JWTs remain valid until their short expiry after logout
• Authentication rate limits are process-local (no Redis for throttling; not cluster-wide); multi-instance deployments should also throttle at the gateway
• Ownership helpers do not replace query scoping (IDOR remains a caller concern)
• HSTS is opt-in (AUTH_ENABLE_HSTS) under production HTTPS assumptions
• When Background Jobs delivers security email, RQ may temporarily hold raw recovery tokens in job arguments (SQL stores digests only)
• Webhooks are outgoing-only; Background Jobs use RQ only; Files storage is local or S3-compatible

---

Contributing

See CONTRIBUTING.md and docs/development.md.

uv sync
uv run pytest
uv run forge --help

---

License

GPL-3.0-only