DDD Clean Architecture Payment Service Demo

This project is a Clean Architecture + DDD style FastAPI backend for a simple payment execution flow.

• app_simple: A minimal example demonstrating Clean Architecture principles.
• app_full: A more complete implementation with additional layers and features.

Managing both apps with uv (single workspace)

This repo is configured as a uv workspace with a shared lockfile and single virtual environment. Both app_simple and app_full are workspace members, so dependencies are resolved once and reused by both.

First-time setup

# Optional: pin a Python version for the workspace
uv python pin 3.13

# Resolve dependencies across all members and create uv.lock
uv lock

# Create one .venv at the repo root and install deps
uv sync

Run the apps

Use --package with the project name from each member's pyproject.toml. Add --app-dir so Python can import the top-level package when running from the repo root.

# Run the simple app (package: clean-arch-simple)
uv run --package clean-arch-simple uvicorn --app-dir app_simple app_simple.interfaces.api.main:app --reload --port 8001

# http://127.0.0.1:8001/docs

# Run the full app (package: clean-arch-full)
uv run --package clean-arch-full uvicorn --app-dir app_full app_full.interfaces.api.main:app --reload --port 8002

# http://127.0.0.1:8002/docs

Notes:

• Both apps share the same .venv created by uv sync at the repo root.
• uv run automatically uses the workspace environment and paths.

Dev extras and tests (full app)

The full app defines a dev extra (pytest, etc.). Include it when syncing, then run tests under that package:

# Install dev extras for the full app
uv sync --package clean-arch-full --extra dev

# Run tests for the full app
uv run --package clean-arch-full pytest -q

Common commands

# Add a dependency for a specific member
uv add --package clean-arch-simple fastapi

# Show the active interpreter and site-packages
uv run -- python -c "import sys,site; print(sys.executable); print(site.getsitepackages())"

# Re-resolve and reinstall after changes
uv lock && uv sync