pyfro

README

pyfro

One command. One stack. Zero feature flags.

An opinionated FastAPI project generator for applications that should start with authentication, persistence, structured logging, and containers already wired together.

Why pyfro?

Starting a backend usually means rebuilding the same foundation before writing the first useful endpoint. pyfro generates that foundation in one shot.

It does not ask which database, auth strategy, migration tool, or project layout you want. The entire point is to generate one complete stack with the same conventions every time.

Generated stack

Area	Technology
API	FastAPI
Environment	uv, Python 3.13, pydantic-settings
Database	PostgreSQL 18, async SQLAlchemy, psycopg
Migrations	Alembic
Cache and sessions	Redis 8
Authentication	JWT access tokens, rotating refresh tokens in HttpOnly cookies
Password hashing	Argon2 via pwdlib
Logging	structlog, request IDs, JSON production logs
Containers	Dockerfile and Podman Compose

The generated authentication module already includes:

• user registration with an automatically created profile;
• login and password verification outside the event loop;
• short-lived JWT access tokens;
• refresh-token rotation backed by Redis;
• HttpOnly refresh cookies;
• logout with refresh-session revocation;
• protected GET /api/v1/auth/me;
• PostgreSQL migrations for users and profiles.

Requirements

• Go 1.24 or newer to install pyfro;
• uv available in PATH;
• Podman with podman-compose, or compatible Docker tooling, to run the full generated stack.

Installation

go install github.com/anxi0uz/pyfro@latest

Make sure your Go binary directory is available in PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

To install from a local clone:

git clone https://github.com/anxi0uz/pyfro.git
cd pyfro
go install .

Quick start

pyfro new myapp
cd myapp
podman-compose up -d --build
podman-compose logs -f app

The API will be available at:

• Swagger UI: http://127.0.0.1:8000/docs
• health check: http://127.0.0.1:8000/health

There are deliberately no generator flags. Every project receives the complete stack.

What the generator does

pyfro new myapp runs a fixed and reproducible workflow:

1. creates a real application with uv init;
2. normalizes the Python package name (my-app becomes my_app);
3. writes the FastAPI modular-monolith structure;
4. adds the fixed dependency set through uv add;
5. lets uv produce pyproject.toml, .python-version, .venv, and uv.lock;
6. creates .env with a cryptographically random JWT secret;
7. adds Alembic, Dockerfile, and Compose configuration.

This means generated lockfiles come from the installed uv version instead of a stale lockfile embedded in the generator.

Generated structure

myapp/
├── src/
│   ├── myapp/
│   │   ├── api/
│   │   │   ├── dependencies.py
│   │   │   ├── middleware.py
│   │   │   └── router.py
│   │   ├── core/
│   │   │   ├── config.py
│   │   │   └── logger.py
│   │   ├── db/
│   │   │   ├── base.py
│   │   │   ├── redis.py
│   │   │   └── session.py
│   │   ├── models/
│   │   │   ├── profile.py
│   │   │   └── user.py
│   │   ├── modules/
│   │   │   └── auth/
│   │   │       ├── dependencies.py
│   │   │       ├── exceptions.py
│   │   │       ├── refresh_session.py
│   │   │       ├── router.py
│   │   │       ├── schemas.py
│   │   │       ├── security.py
│   │   │       └── service.py
│   │   └── main.py
│   └── migrations/
├── .env.example
├── alembic.ini
├── compose.yaml
├── Dockerfile
├── pyproject.toml
└── uv.lock

Local development

Run infrastructure only:

podman-compose up -d postgres redis
uv run alembic upgrade head
uv run fastapi dev src/myapp/main.py

Run the complete containerized application:

podman-compose up -d --build

Developing pyfro

go test ./...
go vet ./...
go build ./...

The project templates are embedded into the final Go binary, so the installed CLI does not depend on template files being present on disk.

Roadmap

• Loki log aggregation;
• Grafana dashboards;
• Prometheus metrics.

These will become part of the same default stack rather than optional generator flags.

License

MIT

Documentation

Overview

Command pyfro generates an opinionated FastAPI application with PostgreSQL, Redis, JWT authentication, Alembic migrations, structured logging, and container configuration.