PyArch

PyArch is a CLI for creating and extending Layered FastAPI projects. It sets up the application structure, database, tests and Alembic, then lets you add CRUD modules and integrations without wiring every file by hand.

Unlike a one-time project template, PyArch keeps a small manifest in the generated project. Later commands use it to understand the project and update the right files.

Why PyArch?

PyArch removes repetitive setup while keeping the generated code readable and ready to change.

• Layered FastAPI project structure
• PostgreSQL and SQLite support
• Complete CRUD modules with models, schemas, repositories, services and routes
• Automatic model and router registration
• JWT auth integration with generated RSA keys
• Protected CRUD routes
• Alembic setup for relational databases
• Tests and dependency setup through uv
• Project-aware generation through pyarch.toml

Quick Start

PyArch requires Python 3.13 or newer and uv.

Install the latest release from PyPI:

pip install pyarch-cli

Create a project and move into it:

pyarch init my_project --database postgres
cd my_project

Copy .env.example to .env and set the database connection values. For PostgreSQL or SQLite, create the first migration:

uv run alembic revision --autogenerate -m "initial"
uv run alembic upgrade head

Run the API:

uv run uvicorn app.main:app --reload

Open http://127.0.0.1:8000/docs to use the generated Swagger UI.

You can now extend the project:

pyarch generate module users
pyarch add integration auth
pyarch generate module tasks --protected
pyarch info

What Gets Generated

A new project includes the application layers, database configuration, test setup and the files needed to run FastAPI:

my_project/
├── app/
│   ├── api/v1/
│   ├── core/
│   ├── db/
│   ├── dependencies/
│   ├── models/
│   ├── repositories/
│   ├── schemas/
│   ├── services/
│   └── main.py
├── tests/
├── alembic/          # PostgreSQL and SQLite only
├── .env.example
├── pyarch.toml
└── pyproject.toml

Each generated CRUD module adds:

• a database model;
• create, update and response schemas;
• repository and service classes;
• list, get, create, update and delete routes;
• CRUD tests;
• model and router registration in the existing application.

Commands

Generation commands must be run inside a project created by PyArch.

Databases and Current Limitations

Current limitations:

• only Layered Architecture is supported;
• generated applications use synchronous database access;
• generated projects are starter scaffolds and still require application-specific configuration and code;
• the manifest format may change before a stable release.

Project Manifest

Every generated project contains pyarch.toml. It records the selected architecture and database, generated modules, enabled integrations and known project paths.

Commands such as generate module, add integration and info read this file instead of trying to infer project state from the directory structure. PyArch updates the manifest after a successful generation step.

Development

Clone the repository and install the development environment:

git clone https://github.com/Allcode-1/PyArch.git
cd PyArch
uv sync

Run the CLI from the checkout:

uv run pyarch --help

Or install the current checkout as an editable CLI tool:

uv tool install --editable .

Architecture and Design

Typer CLI
    ↓
Application services
    ↓
Generators
    ↓
Jinja2 templates
    ↓
Generated FastAPI project
    ↑
pyarch.toml

Roadmap

v0.2

• safer generation and validation;
• rollback on failed generation;
• Redis integration foundation.

v0.3

• Redis integration;
• scheduler integration;
• dry-run mode.

Later

• more architectures;
• plugin system;
• asynchronous database access.

Status

PyArch is in early development. The main workflow is usable, but commands, templates, generated code and the manifest may still change before a stable release.