scaffold-ca-python

What is this?

scaffold-ca-python is a CLI tool that scaffolds production-ready Python projects that follow Clean Architecture. It helps teams start faster by generating the project structure, modules, adapters, entry points, helpers, and pipeline files needed to keep architectural boundaries explicit. It is designed for developers who want repeatable code generation instead of hand-creating the same project pieces over and over.

Installation

Python 3.13 or newer is required.

Install with pip:

pip install scaffold-ca-python

Install with uv:

uv add scaffold-ca-python

You could also use uvx:

uvx scaffold-ca-python [command]

Use --help to see all available command.

Quick Start

1. Create a new Clean Architecture project.

scaffold ca --name my-app

2. Move into the generated project directory.

cd my-app

3. Generate a domain model.

scaffold gm --name order

4. Validate the project structure.

scaffold vs

Commands & Examples

scaffold ca

Scaffold a new Clean Architecture project.

scaffold ca --name my-project

scaffold ca --name my-project --dry-run

scaffold gm

Scaffold a Pydantic v2 domain model and its test stub.

scaffold gm --name order

scaffold gm --name order --dry-run

scaffold guc

Scaffold a use case in domain/usecase/.

scaffold guc --name create_order

scaffold guc --name create_order --dry-run

scaffold gda

Scaffold a driven adapter such as an HTTP client, secrets adapter, or generic outbound adapter.

scaffold gda --type rest-consumer

scaffold gda --type generic --name my_adapter --dry-run

scaffold gep

Scaffold an entry-point adapter for REST APIs, A2A agents, MCP servers, or generic entry points.

scaffold gep --type restapi

scaffold gep --type mcp --with-resources --with-prompts --dry-run

scaffold gep --type mcp --add-tool --name create_file --param path:str --param content:str --returns str --description "Creates a file on disk"

scaffold gh

Scaffold a helper utility module and its test stub.

scaffold gh --name json_parser

scaffold gh --name json_parser --dry-run

scaffold gpipe

Scaffold a CI/CD pipeline configuration for GitHub Actions or Azure Pipelines.

scaffold gpipe --provider github

scaffold gpipe --provider azure --dry-run

scaffold vs

Scan the project for Clean Architecture import violations.

scaffold vs

scaffold vs --dry-run

scaffold dm

Delete a previously generated module and its mirrored test file.

scaffold dm --name order

scaffold dm --name order --dry-run

scaffold up

Update project dependencies using uv lock --upgrade and uv sync.

scaffold up --dry-run

scaffold update-project --dry-run

Technologies

Current Features

• Generates full Clean Architecture project skeletons with scaffold ca.
• Generates domain models with scaffold gm.
• Generates domain use cases with scaffold guc.
• Generates driven adapters with scaffold gda.
• Generates entry points for REST API, agent, MCP, and generic modes with scaffold gep.
• Generates helper utilities with scaffold gh.
• Generates CI/CD pipeline files with scaffold gpipe.
• Validates import boundaries with scaffold vs.
• Deletes generated modules safely with scaffold dm.
• Updates project dependencies with scaffold up.
• Supports --dry-run previews across commands.
• Uses Jinja2 templates for all generated code.
• Validates template context with Pydantic v2.
• Formats terminal output with Rich.
• Enforces static checks with mypy strict and ruff.
• Maintains an 80%+ coverage gate with pytest-cov.

Contributing

1. Fork the upstream repository on GitHub: https://github.com/bancolombia/scaffold-clean-architecture-py
2. Clone your fork.

git clone https://github.com/YOUR-USER/scaffold-clean-architecture-py.git
cd scaffold-clean-architecture-py

3. Set up the development environment.

uv sync

4. Create a feature branch.

git checkout -b your-branch-feature-name

5. Run the test suite.

uv run pytest

6. Check linting.

uv run ruff check src tests

7. Check types.

uv run mypy src

8. Commit your changes and open a pull request.

License

This project is licensed under the MIT License. See LICENSE for the full text.