poleposition 0.0.44

Project lifecycle CLI for starting and growing enterprise FastAPI projects

PolePosition | A lifecycle CLI for FastAPI projects

A project lifecycle CLI that puts teams in pole position when starting, growing, and maintaining enterprise FastAPI projects.

FastAPI speed, Spring/.NET-style project discipline, without turning FastAPI into a heavy framework.

PolePosition helps you keep FastAPI's speed while avoiding the usual setup drag of enterprise backend work. It does more than render a project template: it gives teams commands for project creation, module growth, project checks, and migration workflows as the codebase evolves.

Starting a PolePosition project.

Installation

PolePosition recommends a uv-first workflow for installation, dependency sync, migrations, and local development. It also works with pip and a normal Python virtual environment.

uv tool install poleposition

or

pip install poleposition

---

Quick Start

Recommended uv workflow:

polepos start myapp --install
cd myapp
cp .env.example .env
polepos db upgrade

uv run python -m myapp.run

Open your API documentation:

http://127.0.0.1:8000/docs

For manual setup, Docker, and detailed command usage, see the sections below or the Getting Started guide.

---

Example Output

$ polepos start myapp --install
Created project: myapp

Installing project dependencies...
Dependencies installed successfully with uv.

Next steps:
  cd myapp
  cp .env.example .env
  polepos db upgrade
  uv run python -m myapp.run

Why PolePosition?

PolePosition is named for the same reason teams use it: to start enterprise FastAPI development from pole position and keep it there as the project grows.

FastAPI projects should start fast, clean, and predictable, then stay easy to extend when the target is a larger production system.

PolePosition provides:

• A scalable project structure
• Environment-based configuration
• Alembic-based database migrations
• Lifecycle commands for project creation, module growth, project checks, and database migrations
• Built-in logging
• JWT-based endpoint authentication foundations
• Testing setup
• Module-oriented organization for growing codebases
• A ready-to-run FastAPI application

Less boilerplate at project creation. Less lifecycle friction as the app grows.

---

Coming From Spring Boot or ASP.NET Core?

PolePosition is useful for teams coming from Spring Boot or ASP.NET Core who like explicit project structure, migration workflows, configuration boundaries, logging conventions, tests, and module-oriented growth, but want to keep the speed and directness of FastAPI.

It is not a heavy framework on top of FastAPI. It gives FastAPI projects a predictable lifecycle: start the project, add modules, validate structure, and manage migrations without hiding the application code.

---

Why not just FastAPI?

FastAPI is excellent, but turning it into a team-ready backend lifecycle often involves:

• Recreating the same structure
• Setting up logging and configuration
• Defining module boundaries
• Wiring database foundations
• Organizing modules manually
• Adding new modules without drifting from conventions
• Keeping database migrations and model imports aligned

PolePosition removes that overhead with CLI workflows that create the project, grow the codebase, validate the project contract, and keep migrations first-class.

---

Documentation Map

Use these files to understand the repo quickly:

• Published Docs
• Source Repository
• Getting Started
• CLI Reference
• Module Templates
• Auth Workflow
• Configuration Reference
• Data Structures
• Database and Migrations
• Spring and .NET Module Guide
• Architecture
• Feature Status
• Project Checks
• Upgrade Reports
• Integration Guides
• Troubleshooting and FAQ
• Release and Upgrade Notes
• Examples
• Changelog
• Agent Guide

Build the documentation site locally:

npm install
npm run start

The documentation site uses Docusaurus and requires Node.js >=20.

Usage

Create a project

polepos start myapp --install

--install runs uv sync --extra dev when uv is available. If uv is not available, it creates .venv and installs the generated project with pip. It does not run migrations; after copying .env.example to .env, run polepos db upgrade. --no-bytecode configures generated migration and runtime commands to start with PYTHONDONTWRITEBYTECODE=1, preventing bytecode cache writes from interpreter startup during common local workflows.

Use --db to choose the generated database posture without an interactive prompt:

polepos start myapp --db sqlite
polepos start myapp --db postgres
polepos start myapp --db none

sqlite is the default and preserves the standard DB-ready starter. postgres uses a PostgreSQL DATABASE_URL and matching Docker database name. none omits SQLAlchemy, Alembic, DATABASE_URL, migrations, and generated db/ wiring; use --api-only modules until you intentionally add persistence.

Project names:

• Must not be empty
• Must not contain whitespace
• Must not contain path separators like / or \
• May use hyphens like my-app
• Are normalized to a Python package name like my_app

Manual setup

With uv:

polepos start myapp
cd myapp

cp .env.example .env
uv sync --extra dev
polepos db upgrade

uv run python -m myapp.run

With pip:

polepos start myapp
cd myapp

cp .env.example .env
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
polepos db upgrade

python -m myapp.run

Add modules

polepos add module garage
polepos add module customers --template crud --pagination --timestamps
polepos add module accounts --template crud --tenant-scoped --auth-required
polepos add module assistant --template ai-prompt
polepos add module webhook --api-only

standard is the default template for REST and domain modules. crud generates list/create/get/update/delete routes and can opt into enterprise CRUD concerns such as pagination, timestamps, soft delete, explicit tenant scoping, and bearer-auth protection. ai-prompt adds a provider-agnostic LLM endpoint skeleton with module-local prompt orchestration and shared integrations/llm adapters. api-only generates router, schemas, a module-local services/ package, and tests without model, repository, or database wiring. Use --api-only as a shortcut for --template api-only.

Generated module routes are local to their module router. For example, the standard and API-only starters use @router.get("/") inside the module, then PolePosition registers that router in src/<package>/api/router.py with a module prefix:

api_router.include_router(customers_router, prefix="/customers", tags=["customers"])

With the generated API prefix, that route becomes GET /api/v1/customers/. Another module can also define @router.get("/") because it is registered with its own prefix.

Generated module schemas are starting contracts, not final domain design. Database-backed templates generate names such as CustomerCreate, CustomerUpdate, and CustomerRead; API-only templates generate CustomerRequest and CustomerResponse; AI prompt modules generate CustomerPromptRequest and CustomerPromptResponse. You can rename or replace those schemas after generation, but update the module router, service, repository, generated tests, and migrations together. polepos check validates generated lifecycle wiring, while pytest validates schema imports, request fields, service behavior, and response shapes. See Module Templates for the full schema contract guidance.

CRUD feature options are documented in Module Templates. They require --template crud and can be combined:

polepos add module customers --template crud \
  --pagination \
  --timestamps \
  --soft-delete \
  --tenant-scoped \
  --auth-required

Remove modules

polepos remove module garage
polepos remove module garage --trace
polepos remove module garage --force
polepos remove module garage --wiring-only

remove module deletes the module directory and generated tests, then removes the module export, router include, database-backed module model import, and .poleposition.toml module entry from the managed files. It stops before deleting files if the module wiring has drifted away from a managed layout, or if the module directory or generated tests appear to contain custom changes.

CRUD modules generated with options record those options in the manifest, for example crud[pagination,timestamps,tenant-scoped]. remove module uses that metadata when deciding whether the generated CRUD files are still pristine.

Only the PolePosition-generated wiring is removed automatically. If api/router.py, db/models.py, or modules/__init__.py also contains custom references to the same module, the command reports the unmanaged reference and leaves the module directory in place. Remove or rewrite those custom references explicitly, then rerun the command.

If the module directory was already deleted manually, rerun polepos remove module <name> to clean remaining generated tests, manifest metadata, and managed router, model, and export wiring.

Use --trace to preview the files that would be removed or updated without changing the project. Use --force only when you intentionally want to remove a customized module directory. If an expected generated file has become undecodable as text, PolePosition treats it as a modified generated file; a normal remove stops, and --force can still remove the module directory.

Use --wiring-only when you want to keep a customized module directory but remove PolePosition-managed references to it. This mode cleans module exports, router wiring, database-backed module model imports, and generated tests. It does not delete the module directory or shared integration scaffold. If the preserved directory should no longer be part of the PolePosition lifecycle, move, delete, or rewire it before expecting polepos check to pass.

The command does not change the live database. If a removed database-backed module had a table and you want that table removed too, create and review a migration after the code cleanup:

polepos db revision -m "remove garage table"
polepos db upgrade

If you want to keep the table or data, stop after polepos remove module and do not generate a drop-table migration.

Delete a project

polepos delete myapp
polepos delete myapp --trace
polepos delete myapp --force

delete removes a whole generated project directory, including the in-project .venv. Use it to discard a project created with the wrong name or configuration and start over.

It only deletes a directory that contains a .poleposition.toml manifest, so it will not remove an unrelated folder, and it refuses to delete the current directory or a parent of it. Run it from outside the project, for example from the directory where you ran polepos start. Without --force it asks for confirmation and aborts on any answer other than y. Use --trace (alias --dry-run) to preview, and --force (alias -y) to skip the prompt.

delete removes local files only; it never changes a database.

Add integrations

polepos add integration kafka
polepos add integration rabbitmq
polepos add integration redis
polepos add integration rq

Integration commands add helper modules, test doubles, settings, .env.example values, and transport dependencies. Kafka uses aiokafka, RabbitMQ uses aio-pika, Redis uses redis, and RQ uses rq for Redis-backed background jobs. Long-running consumers and workers are intentionally left as explicit runtime code instead of being started inside the API process.

Data structures

PolePosition also exposes a small runtime namespace for structures Python does not provide as first-class built-in containers:

from polepos.data import IndexedPriorityQueue, LRUCache, SortedDict, Trie

These structures are dependency-free and process-local. Use them for local indices, bounded caches, scheduling helpers, graph workflows, and test doubles. Use Redis, PostgreSQL, Kafka, RabbitMQ, or RQ when state must be shared across workers or persisted outside the process.

Project checks

polepos check
polepos check --json
polepos check --fix

check runs the core project health checks for the current PolePosition project. It validates project identity, generated structure, Alembic config, managed markers, starter module router wiring, added module lifecycle wiring, orphan generated references, and opt-in integration wiring used by commands such as polepos add module, polepos remove module, and polepos add integration.

When .poleposition.toml is present, generated integration entries must use unquoted TOML booleans such as kafka = true or kafka = false. Integration settings and env values are matched as active keys, not comments or loose substrings. A commented required value such as # KAFKA_BOOTSTRAP_SERVERS=... is reported as missing, while optional generated examples such as # KAFKA_COMPRESSION_TYPE= and # LLM_MAX_TOKENS= may stay commented until needed.

Use it after adding modules or integrations, after resolving merge conflicts in managed files, and before handing a project to another teammate or coding agent. The default command is read-only: it reports drift but does not rewrite files, install dependencies, run migrations, or contact external services. Use polepos check --fix when you want PolePosition to restore safe managed markers before checking again. For api/router.py, marker repair keeps # polepos:router-includes outside complete api_router.include_router(...) calls, including multi-line includes.

Failed checks include stable PPCHK issue codes and Fix: hints so humans, coding agents, and CI logs can refer to the same remediation.

Use polepos check --json in CI or agent workflows when you need a machine-readable result. The JSON output includes passed, project_root, package_name, and an issues list with code, message, and remediation.

The checks are organized into three layers:

• Core checks for project identity, generated structure, Alembic files, and managed markers
• Lifecycle checks for starter routing, added module router/model/test wiring, and orphan remnants
• Integration checks for Kafka, RabbitMQ, Redis, RQ, LLM, and auth workflow files, active settings/env values, and dependencies

See Project Checks for detailed user guidance and the agent-facing check contract.

Safe customization boundaries

Generated projects are normal FastAPI projects. Edit module internals for the real domain: models, schemas, repositories, services, routers, migrations, and tests.

When changing generated module schemas, treat the schema, router, service, repository, and generated tests as one contract. Deleting or renaming <ClassName>Create, <ClassName>Read, <ClassName>Request, or similar schema classes without updating their imports usually breaks pytest or app startup.

Avoid changing the lifecycle contract unless the team intentionally owns that surface manually:

• Do not remove or rename # polepos:* managed markers.
• Do not rewrite managed router includes, model imports, module exports, integration settings, or .env.example values into a shape the CLI cannot recognize.
• Keep required generated settings and env values active; use comments only for optional examples or explanatory notes.
• Do not delete generated module directories by hand. Use polepos remove module <name> so generated wiring and tests are cleaned too.
• Do not move generated core files such as api/router.py, db/models.py, settings.py, .env.example, .poleposition.toml, or Alembic files.
• Do not create database tables during app startup; keep schema changes in Alembic migrations.

After structural edits or merge-conflict resolution, run polepos check.

Database commands

polepos db upgrade
polepos db revision -m "add garage table"
polepos db downgrade -1

Database commands prefer uv run alembic ... when uv is available. Without uv, they run Alembic through the active virtualenv, the project .venv, or the first python on PATH.

Use polepos db for the normal local lifecycle. It wraps Alembic while keeping the command flow consistent with polepos start, module add/remove commands, and polepos check. For advanced Alembic flags, you can still run uv run alembic ... directly.

Alembic works through SQLAlchemy dialects. The practical migration-managed database targets are PostgreSQL, MySQL/MariaDB, SQLite, Microsoft SQL Server, and Oracle. Stores with external SQLAlchemy dialects, such as ClickHouse, should usually be treated as explicit integrations unless the project owns and reviews their custom DDL workflow.

See Database and Migrations for the full migration workflow.

Docker workflow

Generated projects include a Dockerfile, .dockerignore, and compose.yaml so you can start the app with PostgreSQL in containers.

cp .env.example .env
docker compose up --build
docker compose run --rm app uv run alembic upgrade head

The compose setup uses the generated run.py entrypoint and overrides DATABASE_URL so the app talks to the bundled PostgreSQL service. If you already have PostgreSQL on 5432, change POSTGRES_PORT in .env before starting the compose stack.

The Docker example runs Alembic directly inside the generated app container because that image contains the generated application dependencies, not the PolePosition CLI.

Logging

Generated projects use get_logger(__name__) from bootstrap.logging as the preferred logging entrypoint.

from shop_api.bootstrap.logging import get_logger

logger = get_logger(__name__)

Runtime configuration

Generated projects include src/<package>/run.py as the preferred local and production-friendly entrypoint.

Use:

uv run python -m shop_api.run

Runtime code is split intentionally:

• app.py defines create_app() and wires FastAPI, middleware, exception handlers, logging, and the API router when the factory is called.
• main.py creates the ASGI-level app used by Uvicorn import strings such as shop_api.main:app.
• run.py is the local process entrypoint that reads runtime settings, prints the startup table, and starts Uvicorn.

get_settings() and setup_logging() are evaluated inside create_app(), not at app.py import time. This keeps tests and dynamic environment overrides from inheriting stale import-time configuration.

The runner is configured from settings.py and .env, including:

• APP_HOST
• APP_PORT
• APP_RELOAD
• LOG_LEVEL
• UVICORN_WORKERS
• UVICORN_ACCESS_LOG
• UVICORN_PROXY_HEADERS
• UVICORN_FORWARDED_ALLOW_IPS
• UVICORN_SERVER_HEADER
• UVICORN_DATE_HEADER
• UVICORN_TIMEOUT_KEEP_ALIVE
• UVICORN_TIMEOUT_GRACEFUL_SHUTDOWN
• UVICORN_TIMEOUT_WORKER_HEALTHCHECK
• UVICORN_LIMIT_CONCURRENCY
• UVICORN_LIMIT_MAX_REQUESTS
• UVICORN_LIMIT_MAX_REQUESTS_JITTER
• UVICORN_BACKLOG

When the generated runner starts, it prints a compact startup table with the current service name, environment, API prefix, database backend, host, port, worker count, and docs URL.

CORS

Generated projects include settings-driven CORS support with development defaults for common localhost frontend origins.

You can control it from .env with:

• CORS_ENABLED
• CORS_ALLOW_ORIGINS
• CORS_ALLOW_ORIGIN_REGEX
• CORS_ALLOW_CREDENTIALS
• CORS_ALLOW_METHODS
• CORS_ALLOW_HEADERS
• CORS_EXPOSE_HEADERS
• CORS_MAX_AGE

The list-style fields accept JSON arrays in .env.

Authentication

Generated projects include a minimal JWT-based authentication foundation with:

• a public GET /api/v1/status endpoint
• get_current_user and require_roles(...) helpers

Relevant auth settings:

• AUTH_SECRET_KEY
• AUTH_ALGORITHM
• AUTH_ACCESS_TOKEN_EXPIRE_MINUTES
• AUTH_ISSUER

JSON logging

Generated projects support both text and JSON logging formats.

Use:

• LOG_FORMAT=text for local development
• LOG_FORMAT=json for structured production logging

The JSON formatter includes:

• timestamp
• level
• logger
• message
• app_name
• environment
• request_id

When to use which command

PolePosition is a lifecycle CLI, so the commands are meant to be used over time, not only on day one:

• polepos start when you want to create a new FastAPI project with the PolePosition structure
• polepos add module when you want to add a new REST/domain module, CRUD module, API-only module, or AI prompt module to an existing project
• polepos add auth when you want to add the optional database-backed registration and token workflow
• polepos remove module when you want to remove a generated module and its managed wiring
• polepos delete when you want to delete a whole generated project directory and start over
• polepos add integration kafka when you want Kafka producer and consumer wiring in an existing project
• polepos add integration rabbitmq when you want RabbitMQ publisher and consumer wiring in an existing project
• polepos add integration redis when you want shared Redis cache helpers in an existing project
• polepos add integration rq when you want Redis-backed background job helpers in an existing project
• polepos check when you want to validate the project contract: generated structure, Alembic config, managed markers, module wiring, and integration wiring
• polepos check --fix when safe managed markers should be restored before validation
• polepos db status when you want to inspect current and target Alembic revisions
• polepos db upgrade when you want to apply migrations to the database
• polepos db revision -m "..." when you changed models and need a new migration
• polepos db downgrade when you need to roll back a migration
• polepos upgrade when you want a read-only project upgrade readiness report

Examples

Concrete scenario guides live in Examples:

• auth foundation workflow
• PostgreSQL-backed HTML swap workflow
• Kafka quick-start producer/consumer workflow
• RabbitMQ quick-start publisher/worker workflow
• Redis cache-aside workflow
• OpenAI prompt endpoint workflow

Help and version

polepos help
polepos help start
polepos help add module
polepos help db revision
polepos version

polepos help prints the full CLI usage and command reference. Pass a command path to get focused help for one command, similar to polepos help remove module.

---

CLI

polepos help
polepos help <command> [subcommand]
polepos start <name> [--install] [--no-bytecode] [--db sqlite|postgres|none]
polepos startproject <name> [--install] [--no-bytecode] [--db sqlite|postgres|none]
polepos add module <name>
polepos add module <name> --template crud
polepos add module <name> --template crud [--pagination] [--timestamps]
polepos add module <name> --template crud [--soft-delete] [--tenant-scoped]
polepos add module <name> --template crud [--auth-required]
polepos add module <name> --template ai-prompt
polepos add module <name> --api-only
polepos add auth
polepos remove module <name> [--force] [--trace] [--wiring-only]
polepos delete <name> [--force] [--trace]
polepos add integration kafka
polepos add integration rabbitmq
polepos add integration redis
polepos add integration rq
polepos check
polepos check --json
polepos check --fix
polepos db status
polepos db upgrade [target]
polepos db revision -m "<message>"
polepos db downgrade <target>
polepos upgrade
polepos version

For option-by-option behavior, examples, and lifecycle notes, see the CLI Reference.

---

Project Structure

myapp/
├─ AGENTS.md
├─ Dockerfile
├─ compose.yaml
├─ .poleposition.toml
├─ alembic.ini
├─ migrations/
│  └─ versions/
├─ pyproject.toml
├─ .dockerignore
├─ .env.example
├─ src/
│  └─ myapp/
│     ├─ run.py
│     ├─ main.py
│     ├─ app.py
│     ├─ settings.py
│     ├─ bootstrap/
│     ├─ api/
│     ├─ db/
│     ├─ domain/
│     └─ modules/
│        └─ status/
└─ tests/
   ├─ integration/
   └─ unit/

---

Status Endpoint

Check if your service is running:

GET /api/v1/status

{
  "status": "ok",
  "service": "myapp",
  "environment": "development",
  "version": "0.1.0",
  "uptime_seconds": 12,
  "timestamp": "2026-04-26T12:00:00Z"
}

---

Philosophy

PolePosition is built around a few principles:

• Lifecycle-oriented: supports project creation, growth, checks, and migrations
• Minimal: no unnecessary abstractions
• Opinionated: sensible defaults
• Extensible: easy to grow into larger systems

The CLI is intentionally lightweight and avoids heavy templating engines. Templates are an implementation detail; the product surface is the project lifecycle.

---

Example Workflow

Here is a concrete example for a new PostgreSQL-backed FastAPI REST API project.

Create the project and install dependencies:

uv tool install poleposition
polepos start shop-api
cd shop-api
cp .env.example .env
uv sync --extra dev

Or use the generated Docker workflow:

docker compose up --build
docker compose run --rm app uv run alembic upgrade head

That Docker command runs Alembic directly inside the generated app container. For the host workflow, use polepos db upgrade after configuring .env.

Point the project to PostgreSQL in .env:

DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/shop_api

Apply the initial migration and start the API:

polepos db upgrade
uv run python -m shop_api.run

Add a new REST module:

polepos add module customers

Extend src/shop_api/modules/customers/model.py and schemas.py for your domain, then generate and apply a migration:

polepos db revision -m "add customers table"
polepos db upgrade

At that point, your project has:

• FastAPI app structure
• PostgreSQL-ready SQLAlchemy setup
• Alembic migration workflow
• A generated REST module with router, schemas, module-local services, repository, and tests

That is the core PolePosition flow: start fast, add modules as the API grows, and evolve the database schema through the CLI.

Example: build a users REST API

If you want a REST API that returns users, the flow is:

Generate the module:

polepos add module users

Update src/shop_api/modules/users/model.py with user fields such as:

class Users(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    email: Mapped[str] = mapped_column(String(255), unique=True)
    full_name: Mapped[str] = mapped_column(String(120))
    is_active: Mapped[bool] = mapped_column(default=True)

Update schemas.py so the API returns those fields, then create and apply a migration:

polepos db revision -m "create users table"
polepos db upgrade

At that point, you already have the generated router shape for:

GET  /api/v1/users/
POST /api/v1/users/

Those paths come from the module-local @router.get("/") and @router.post("/") handlers being included once under the /users prefix in api/router.py.

From there, you refine the generated module for your actual domain instead of starting from an empty project structure.

---

Python Support

The PolePosition CLI supports Python >=3.10.

Generated FastAPI projects target Python >=3.11, as declared in the generated project pyproject.toml. This lets the CLI remain lightweight while generated applications use a modern FastAPI, Pydantic, SQLAlchemy, and Alembic baseline.

The repository CI currently runs the CLI test suite on Python 3.10, 3.11, 3.12, 3.13, and 3.14. Generated-project e2e coverage runs on Python 3.11.

Test And CI Automation

Workflow	Trigger	What it runs
CI	push, pull request, manual dispatch	Ruff lint + format check (Google Python Style Guide); repo test suite on Python 3.10, 3.11, 3.12, 3.13, and 3.14; Docusaurus production build
E2E	release tags, relevant pull requests, manual dispatch	Generated-project non-Docker e2e smoke tests on Python 3.11
Release	published GitHub release	Build and verify Python distributions, then publish to PyPI with Trusted Publishing
Deploy Docs	pushes to main, manual dispatch	Docusaurus production build and GitHub Pages deploy

The CI workflow runs pytest with pytest-cov, prints a terminal coverage report, and uploads coverage.xml as a per-Python-version workflow artifact. Coverage is currently informational; no minimum threshold is enforced yet.

Docker e2e coverage exists as an opt-in local or release-readiness smoke path via the docker_e2e pytest marker. It is intentionally not run on every pull request because it requires Docker and a compose-capable environment.

The Release workflow uses PyPI Trusted Publishing, so it does not require a PYPI_API_TOKEN repository secret. PyPI must trust the polepos/poleposition repository, .github/workflows/release.yml, and the pypi GitHub Actions environment before the first publish.

---

Contributing

Contributions are welcome. Feel free to open an issue or submit a pull request.

See CONTRIBUTING.md and the Contributing guide for development setup, running the tests (including opt-in end-to-end tests), project layout, and common tasks.

Code style

Python code follows the Google Python Style Guide, enforced automatically with Ruff (80-column lines, sorted imports, pep8-naming, and exception chaining). The CI workflow gates every pull request on it. Before pushing:

ruff check pole_position polepos
ruff format pole_position polepos

See Code Style for the full rule set and rationale.

---

License

MIT

License