pattern-stack

Pattern Stack

A Python framework implementing Atomic Architecture v2.1 - a layered architecture pattern for building maintainable applications.

Key Features

• 🎯 Field Abstraction: Clean, intuitive model definitions without SQLAlchemy boilerplate
• 🧬 Reusable Patterns: Mix-and-match behavioral patterns (Catalog, Actor, Event, Categorical, Relational)
• 🏗️ Atomic Architecture: Clear separation of concerns with unidirectional dependencies
• 🚀 Progressive Enhancement: Start simple, add complexity only when needed
• 🔄 Event System: Built-in event bus for decoupled communication
• 💾 Cache Subsystem: Swappable cache backends (Memory, Redis)
• 🛡️ Type-Safe: Full type hints with MyPy validation

Installation

As a Package Dependency

Note: Pattern Stack is not yet published to PyPI. Install from GitHub:

# Using uv (recommended)
uv add git+https://github.com/pattern-stack/backend-patterns.git

# Or with pip
pip install git+https://github.com/pattern-stack/backend-patterns.git

# For a specific version/tag
uv add git+https://github.com/pattern-stack/[email protected]

# For local development (editable install)
git clone https://github.com/pattern-stack/backend-patterns.git
cd backend-patterns
uv add -e .

Coming soon: PyPI package installation with uv add pattern-stack

For Development

# Clone the repository
git clone https://github.com/pattern-stack/backend-patterns.git
cd backend-patterns

# Install with uv
uv sync --extra dev --extra test

# Install pre-commit hooks
make pre-commit-install

# Start local services
make services-up-with-ui

Quick Start

Zero-Config FastAPI Application

Get started with a fully configured application in seconds:

from pattern_stack.atoms.app import create_app
from pattern_stack.atoms.config.settings import get_settings

# Create app with automatic event system, database, and API setup
app = create_app(get_settings())

# That's it! You now have:
# - Event system with auto-configured backend (database/memory)
# - Health and readiness endpoints (/health, /ready)
# - CORS and logging middleware
# - Exception handling

Simple Models with Field Abstraction

from pattern_stack.atoms.patterns import BasePattern, Field, CatalogPattern, EventPattern
from decimal import Decimal

# Simple model using Field abstraction - no SQLAlchemy knowledge needed!
class Task(BasePattern):
    __tablename__ = "tasks"

    title = Field(str, required=True, max_length=200)
    description = Field(str, nullable=True, max_length=1000)
    completed = Field(bool, default=False)
    priority = Field(int, default=3, min=1, max=5)

# Advanced model combining patterns with Field
class Product(CatalogPattern, EventPattern):
    """Product with inventory management and lifecycle states."""
    __tablename__ = "products"

    class Pattern:
        # CatalogPattern config
        entity = "product"
        reference_prefix = "PROD"

        # EventPattern config - state machine
        states = {
            "draft": ["published", "discontinued"],
            "published": ["out_of_stock", "discontinued"],
            "out_of_stock": ["published", "discontinued"],
            "discontinued": []
        }
        initial_state = "draft"

        # Both patterns support change tracking
        track_changes = True
        emit_state_transitions = True

    # CatalogPattern provides: name, code, description, is_active, display_order,
    #                          stock_quantity, reserved_quantity, pricing fields
    # EventPattern provides: state, state transitions, event emission

    # Add domain-specific fields using Field abstraction:
    warranty_months = Field(int, default=12, min=0, max=120)

Field Abstraction Benefits

Pattern Stack's Field abstraction eliminates the need for SQLAlchemy boilerplate:

# Clean, intuitive field definitions
email = Field(str, required=True, unique=True, max_length=320)
age = Field(int, min=0, max=150)
status = Field(str, default="active", choices=["active", "pending", "archived"])

# Instead of verbose SQLAlchemy syntax:
# email: Mapped[str] = mapped_column(String(320), nullable=False, unique=True)

Architecture Overview

Pattern Stack is a framework implementing Atomic Architecture v2.1 principles. The framework provides building blocks (atoms/) that users integrate into their applications to build features/, molecules/, and organisms/.

Core Principles

1. Unidirectional Dependencies: Dependencies flow downward only (Organisms → Molecules → Features → Atoms)
2. Single Responsibility: Each layer has one clear purpose
3. Pattern-Based Development: Reusable patterns for common behaviors
4. Clean Boundaries: No business logic in models, no permissions in services

Framework Structure (atoms/ only)