python-architecture

# Python Application Architecture Modern Python application architecture following functional core / imperative shell pattern, Domain-Driven Design, and type-safe data modeling. ## Core Principle: Functional Core / Imperative Shell Separate pure business logic from side effects: - **Functional Core**: Pure functions, business logic, no IO - **Imperative Shell**: Coordinates external dependencies, handles side effects See [references/functional-core.md](references/functional-core.md) for detailed patterns and examples. ## Layered Architecture Follow bottom-up dependency flow: ``` Router/Handler → Service → Repository → Entity → Database ``` Each layer depends only on layers below. **Responsibilities:** - **Entity**: Domain models, validation, business rules, data transformations (fromRequest, toRecord, toResponse) - **Repository**: Abstract storage interface, returns domain entities - **Service**: Business workflows, orchestrates entities and repositories - **Router/Handler**: HTTP handling, delegates to services ## Domain Models ### Entity Example ```python from dataclasses import dataclass from uuid import UUID from decimal import Decimal @dataclass class Order: """Entity - has identity and encapsulated behavior""" id: UUID customer_id: UUID total: Decimal status: str def apply_discount(self, rate: Decimal) -> None: """Business rule - encapsulated in entity""" if self.status == "pending": self.total = self.to...