Code Along: Architecture Patterns with Python

The default branch, main, was created from the upstream start tag.

Chapters Completed

I. Building Architecture to Support Domain Modeling

• 1. Domain Modeling

• 2. Repository Pattern

• 3. On Coupling and Abstractions

• 4. API and Service Layer

• 5. TDD in High and Low Gear

• 6. Unit of Work Pattern

• 7. Aggregates and Consistency Boundaries

II. Event-Driven Architecture

• 8. Events and the Message Bus

• 9. Going to Town on the Message Bus

• 10. Commands and Command Handler

• 11. Using Events to Integrate Microservices

• 12. Command-Query Responsibility Separation

• 13. Dependency Injection

Getting Started

Clone and set up the project

git clone git@github.com:evokateur/python-architecture.git
cd python-architecture
pyenv shell 3.12
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure environment

Create a .env file based on .env.example:

cp .env.example .env

You have two options for running the application:

Option 1: Lightweight setup (Railway PostgreSQL + local Flask)

Edit .env and set your Railway PostgreSQL connection string:

POSTGRES_URI=postgresql://user:password@host:port/database

Other important settings in .env:

• FLASK_RUN_PORT=5005 (default port for local Flask)
• FLASK_APP=entrypoints/flask_app.py
• FLASK_ENV=development

Option 2: Docker-based setup

Use the default values from .env.example (no changes needed). Docker Compose will run both PostgreSQL and the Flask app in containers.

Add semi-upstream† remote for reference

† a fork I will test the chapter branches in, but not code along in

git remote add upstream git@github.com:evokateur/python-architecture-code.git
git fetch upstream

Finding the upstream branches for a chapter

git branch -r -l 'upstream/chapter_07*'

Development Workflow

Option 1: Lightweight setup (Railway + local Flask)

Start the Flask development server (connects to Railway PostgreSQL):

make flask

Stop the Flask server:

make unflask

Check Flask logs:

cat flask.log

Option 2: Docker-based setup

Start all services (PostgreSQL + Flask in containers):

make up

Stop all services:

make down

View logs:

make logs

Running tests

# Run all tests
make test

# Run specific test types
pytest tests/unit --tb=short
pytest tests/integration --tb=short
pytest tests/e2e --tb=short

# Watch tests during development
make watch-tests

Code formatting

make black