@dynokostya/just-works 1.0.0

package/.claude/skills/ddd-architecture-python/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: ddd-architecture-python
+description: Apply when implementing Domain-Driven Design patterns in Python (.py) files. Covers tactical patterns (entities, value objects, aggregates, domain events, repositories), layered architecture with dependency inversion, persistence strategies, validation boundaries, and common DDD anti-patterns. Best suited for projects with complex business rules spanning multiple entities.
+---
+
+# Domain-Driven Design in Python
+
+Match the project's existing domain model conventions. When uncertain, read 2-3 existing aggregate or entity modules to infer the local style. Check for existing base classes, event infrastructure, and repository patterns before introducing new ones. These defaults apply only when the project has no established convention.
+
+## Never rules
+
+These are unconditional. They prevent structural defects regardless of project style.
+
+- **Never put business logic in service layers while domain models are empty data bags.** This is the anemic domain model. If all methods live in services and entities are just data carriers, you have Transaction Scripts with extra mapping cost. Move behavior that enforces invariants into the entity or aggregate that owns the state.
+- **Never create repositories for anything other than aggregate roots.** Repositories exist per aggregate root, not per entity. Accessing child entities bypassing the aggregate root breaks consistency boundaries. `OrderLineRepository` is always wrong if `OrderLine` belongs to an `Order` aggregate.
+- **Never use `@dataclass(frozen=True)` for entities.** Frozen dataclasses enforce structural equality (compare all fields). Entities have identity -- two `User` objects with the same `id` are the same user even if `email` changed. Use `@dataclass(eq=False, slots=True)` and implement identity-based `__eq__` and `__hash__` on the id field.
+- **Never use `unsafe_hash=True` on mutable dataclasses.** It makes mutable objects hashable, causing subtle bugs when attributes change after insertion into sets or dict keys. Use frozen for value objects, custom hash for entities.
+- **Never let domain models import from infrastructure.** The dependency arrow points inward: infrastructure -> application -> domain. Domain models must not import SQLAlchemy, Pydantic, httpx, or any external framework.
+- **Never duplicate validation between API layer and domain layer.** Pydantic validates input shape at the boundary (type coercion, required fields). Domain validates business invariants (order total can't be negative, user can't have more than 5 active subscriptions). These are different concerns.
+- **Never apply tactical DDD patterns to CRUD-only modules.** If a bounded context has no business invariants beyond "save and retrieve," use plain service functions or direct ORM operations. Strategic DDD (bounded contexts, ubiquitous language) is almost always valuable; tactical DDD is conditional.
+
+## Tactical patterns
+
+| Pattern | Python Implementation | Use When | Skip When |
+|---------|----------------------|----------|-----------|
+| **Value Object** | `@dataclass(frozen=True, slots=True)` | Equality by value (Money, Email, DateRange) | Simple strings/ints with no validation |
+| **Entity** | `@dataclass(eq=False, slots=True)` + custom `__eq__`/`__hash__` on id | Objects with lifecycle and identity | Lookup tables, config records |
+| **Aggregate Root** | Entity + `_events: list[Event]` + invariant methods | Multi-entity consistency boundaries | Single-entity modules |
+| **Domain Event** | `@dataclass(frozen=True)` inheriting from `Event` base | Side effects: notifications, indexing, cross-context sync | Simple CRUD with no cross-context effects |
+| **Repository** | Protocol in domain, implementation in infrastructure | Aggregate root persistence abstraction | Simple modules -- use ORM directly |
+| **Domain Service** | Plain function or class in domain layer | Logic spanning multiple aggregates | Logic that belongs on a single entity |
+| **Application Service** | Orchestrates repositories, domain objects, UoW | Use case coordination | Don't mix with domain logic |
+| **Factory** | `@classmethod` on entity or aggregate | Complex construction with invariants | Simple `__init__` suffices |
+
+### Value object
+
+```python
+@dataclass(frozen=True, slots=True)
+class Money:
+    amount: Decimal
+    currency: str
+
+    def __post_init__(self) -> None:
+        if self.amount < 0:
+            raise ValueError("Amount cannot be negative")
+        if len(self.currency) != 3:
+            raise ValueError("Currency must be ISO 4217 code")
+
+    def add(self, other: Money) -> Money:
+        if self.currency != other.currency:
+            raise ValueError(f"Cannot add {self.currency} to {other.currency}")
+        return Money(amount=self.amount + other.amount, currency=self.currency)
+```
+
+### Entity with identity equality
+
+```python
+@dataclass(eq=False, slots=True)
+class Order:
+    id: int
+    customer_id: int
+    lines: list[OrderLine]
+    status: OrderStatus
+    _events: list[Event] = field(default_factory=list, repr=False)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Order):
+            return NotImplemented
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        return hash(self.id)
+
+    def add_line(self, sku: str, qty: int, price: Money) -> None:
+        if self.status != OrderStatus.DRAFT:
+            raise OrderFinalizedError(self.id)
+        line = OrderLine(sku=sku, qty=qty, price=price)
+        self.lines.append(line)
+
+    def confirm(self) -> None:
+        if not self.lines:
+            raise EmptyOrderError(self.id)
+        self.status = OrderStatus.CONFIRMED
+        self._events.append(OrderConfirmed(order_id=self.id))
+
+    def collect_events(self) -> list[Event]:
+        events = self._events[:]
+        self._events.clear()
+        return events
+```
+
+Wrong -- frozen dataclass for an entity:
+
+```python
+# WRONG: frozen enforces structural equality, entities have identity
+@dataclass(frozen=True, slots=True)
+class Order:
+    id: int
+    customer_id: int
+    status: OrderStatus  # can't mutate status transitions
+```
+
+## Persistence strategy
+
+Three approaches, ordered by coupling:
+
+| Strategy | Tradeoff | Use When |
+|----------|----------|----------|
+| **Domain models = ORM models** | Coupling to SQLAlchemy, but zero mapping | <3 aggregates, team <3, domain is simple |
+| **Imperative mapping** (`map_imperatively`) | Clean separation, moderate setup | Business logic complex enough to test without DB |
+| **Separate models + manual mapping** | Full isolation, high boilerplate | Domain and persistence schemas diverge significantly |
+
+Start with Strategy A. Move to Strategy B when you need to unit-test domain logic without touching the database. Move to Strategy C only when the persistence schema genuinely differs from the domain model.
+
+### Imperative mapping
+
+```python
+# domain/model.py -- pure Python, no SQLAlchemy imports
+@dataclass(eq=False, slots=True)
+class Product:
+    id: int
+    sku: str
+    batches: list[Batch]
+
+# infrastructure/orm.py -- SQLAlchemy mapping, called once at startup
+from sqlalchemy import Table, Column, Integer, String
+from sqlalchemy.orm import registry, relationship
+
+mapper_registry = registry()
+
+product_table = Table(
+    "products",
+    mapper_registry.metadata,
+    Column("id", Integer, primary_key=True),
+    Column("sku", String(255)),
+)
+
+def start_mappers() -> None:
+    mapper_registry.map_imperatively(Product, product_table, properties={
+        "batches": relationship(Batch),
+    })
+```
+
+## Dependency inversion
+
+| Mechanism | Use When |
+|-----------|----------|
+| **Protocol** | Domain ports consumed by application/infrastructure. No inheritance required. |
+| **ABC** | Infrastructure base classes where implementations share common behavior |
+| **Constructor args** | Default for everything. Explicit, testable, no framework. |
+| **FastAPI Depends** | Request-scoped injection in web handlers |
+
+Protocol for domain ports, constructor injection for wiring:
+
+```python
+# domain/ports.py
+from typing import Protocol
+
+class OrderRepository(Protocol):
+    async def get(self, order_id: int) -> Order: ...
+    async def save(self, order: Order) -> None: ...
+
+# application/services.py
+class ConfirmOrderHandler:
+    def __init__(self, repo: OrderRepository, bus: MessageBus) -> None:
+        self._repo = repo
+        self._bus = bus
+
+    async def handle(self, command: ConfirmOrder) -> None:
+        order = await self._repo.get(command.order_id)
+        order.confirm()
+        await self._repo.save(order)
+        for event in order.collect_events():
+            await self._bus.publish(event)
+```
+
+Wrong -- generic repository with leaked ORM abstractions:
+
+```python
+# WRONG: this is a leaked ORM, not a domain repository
+class Repository[T]:
+    async def filter(self, **kwargs: Any) -> list[T]: ...
+    async def all(self) -> list[T]: ...
+
+# RIGHT: domain-meaningful methods
+class OrderRepository(Protocol):
+    async def get(self, order_id: int) -> Order: ...
+    async def get_pending_orders(self) -> list[Order]: ...
+    async def save(self, order: Order) -> None: ...
+```
+
+## Domain events
+
+Use `@dataclass(frozen=True)` events collected on aggregates. Dispatch via a simple message bus.
+
+```python
+# domain/events.py
+@dataclass(frozen=True)
+class Event:
+    pass
+
+@dataclass(frozen=True)
+class OrderConfirmed(Event):
+    order_id: int
+
+# infrastructure/messagebus.py
+EVENT_HANDLERS: dict[type[Event], list[Callable]] = {
+    OrderConfirmed: [send_confirmation_email, update_inventory],
+}
+
+async def handle(event: Event) -> None:
+    for handler in EVENT_HANDLERS.get(type(event), []):
+        await handler(event)
+```
+
+Domain events are in-process. Integration events cross service boundaries via message queues -- different concern, different infrastructure.
+
+## Validation layers
+
+| Layer | Responsibility | Tool |
+|-------|---------------|------|
+| **API boundary** | Shape, types, required fields | Pydantic `BaseModel` |
+| **Domain** | Business invariants | Entity/aggregate methods, `__post_init__` |
+| **Cross-aggregate** | Multi-aggregate rules | Domain services |
+
+Don't validate the same thing twice. Pydantic checks "is this a valid email string." Domain checks "can this user register with this email given their account state."
+
+## Project structure
+
+### Pragmatic DDD (start here)
+
+```
+src/
+├── ordering/                  # Bounded context = package
+│   ├── domain/
+│   │   ├── model.py           # Entities, VOs, aggregates
+│   │   ├── events.py          # Domain events
+│   │   └── ports.py           # Repository protocols
+│   ├── application/
+│   │   └── handlers.py        # Command/query handlers (thin)
+│   ├── infrastructure/
+│   │   ├── orm.py             # SQLAlchemy mapping
+│   │   └── repository.py      # Repository implementations
+│   └── interface/
+│       ├── router.py          # FastAPI routes
+│       └── schemas.py         # Pydantic request/response
+├── shared/
+│   ├── messagebus.py          # Event dispatch
+│   └── uow.py                # Unit of Work
+└── main.py
+```
+
+Import rules: interface -> application -> domain. Infrastructure -> domain (implements ports). Domain imports nothing from other layers.
+
+### Simple DDD (CRUD-heavy bounded contexts)
+
+```
+src/
+├── notifications/             # Simple context -- no tactical DDD
+│   ├── router.py
+│   ├── schemas.py
+│   ├── service.py             # Business logic (thin)
+│   └── models.py              # ORM models directly
+```
+
+Not every bounded context needs full DDD. Apply tactical patterns where business rules are complex.
+
+## When to use DDD
+
+| Criterion | Use DDD | Skip DDD |
+|-----------|---------|----------|
+| Business invariants | Span multiple entities, enforced transactionally | Single-entity CRUD |
+| Domain complexity | Domain experts disagree on rules | Rules fit on one page |
+| Team size | 3+ developers, domain knowledge distributed | Solo developer, full context in head |
+| Change frequency | Business rules change independently of tech | Schema-driven CRUD, logic is trivial |
+| Bounded contexts | 2+ contexts with different models of same concept | Monolithic domain, single model |
+
+## Anti-patterns
+
+- **Anemic domain model.** All logic in services, entities are bags of data. You have Transaction Scripts with extra mapping cost.
+- **Repository per entity.** Repositories exist only for aggregate roots. `UserRepository`, `OrderRepository` -- yes. `OrderLineRepository` -- no.
+- **DDD theater.** Using vocabulary (aggregate, bounded context, ubiquitous language) without actually modeling the domain. If your "aggregates" don't enforce any invariants, they're just database records.
+- **Over-abstraction.** `IUserRepositoryFactory`, `AbstractDomainServiceBase` -- Python doesn't need this. Protocol + constructor injection is the ceiling.
+- **Premature event sourcing.** Event sourcing is a persistence strategy, not a default. Use it when you need a full audit log or temporal queries. For everything else, it adds rebuild complexity, eventual consistency headaches, and schema evolution pain.
+- **Wrong aggregate boundaries.** If you load an aggregate and it pulls 50 related entities from the database, the boundary is too wide. If you can't enforce a business rule without loading two aggregates, the boundary is too narrow or the rule belongs in a domain service.
+- **Generic repository.** `Repository[T]` with `.filter()` and `.all()` is a leaked ORM abstraction. Repositories expose domain-meaningful methods: `get_pending_orders()`, not `filter(status="pending")`.
+- **Pydantic in domain layer.** Domain models should be pure Python (dataclasses). Pydantic belongs at system boundaries. Coupling domain logic to Pydantic makes unit testing slower and ties domain evolution to a serialization library.
+- **Importing Java/C# patterns wholesale.** Python has no interfaces, no private fields, no explicit getters/setters. Use Protocol (not Interface), `_convention` (not private fields), properties only when computation is needed.

package/.claude/skills/feature-driven-architecture-python/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: feature-driven-architecture-python
+description: Apply when structuring Python projects by business capability (vertical slices). Covers directory layout, feature boundaries, inter-feature communication, database model ownership, migration strategies, boundary enforcement, testing across features, and migration from layered architectures. Best suited for FastAPI and Flask projects with 5+ distinct features.
+---
+
+# Feature-Driven Architecture
+
+Match the project's existing structure. When uncertain, read 3-5 existing feature directories to infer the local conventions. Check for import-linter or PyTestArch configuration in `pyproject.toml`. These defaults apply only when the project has no established convention.
+
+## Never rules
+
+These are unconditional. They prevent coupling and boundary erosion regardless of project style.
+
+- **Never import another feature's ORM models directly.** Features own their models. Cross-feature data access goes through the owning feature's service layer or shared read models. `from src.billing.models import Invoice` inside `src.auth/` is always a defect.
+- **Never create circular imports between features.** If Feature A imports from Feature B and Feature B imports from Feature A, the feature boundaries are drawn wrong. Refactor using events, a shared service, or merge the features.
+- **Never put business logic in routers/views.** Routers handle HTTP concerns (status codes, response formatting). Business logic lives in `service.py` or domain functions within the feature.
+- **Never share Pydantic request/response schemas across features.** Each feature defines its own schemas. Identical DTOs in two features today will diverge tomorrow — duplication is cheaper than the wrong shared abstraction.
+- **Never skip boundary enforcement tooling.** Setup is 15 minutes — a single `independence` contract in `pyproject.toml` and `lint-imports` in CI. Kraken Technologies found that violations appear even on small teams under deadline pressure, and compound quickly. Code review catches logic issues; import-linter catches structural invariants that are tedious and error-prone to verify manually in diffs.
+- **Never use ForeignKey across feature boundaries in new code.** Use plain integer ID fields between features. The referential integrity cost is real but coupling cost is worse. Shared read models are the escape hatch.
+- **Never put feature-specific code in the shared layer.** `shared/` or `core/` contains only cross-cutting infrastructure: auth middleware, database session factory, base classes, pagination, response schemas. If it's specific to one feature, it belongs in that feature.
+- **Never use `extend_existing=True` for cross-feature read models.** It silently merges column definitions into a shared `Table` object (SQLAlchemy issues #7366, #8925). Use database VIEWs mapped to separate ORM classes instead.
+
+## Directory structure
+
+Each feature is a self-contained Python package:
+
+```
+src/
+├── auth/
+│   ├── __init__.py
+│   ├── router.py          # FastAPI APIRouter with endpoints
+│   ├── schemas.py         # Pydantic request/response models
+│   ├── models.py          # SQLAlchemy/ORM models
+│   ├── service.py         # Business logic
+│   ├── dependencies.py    # FastAPI Depends() callables
+│   ├── exceptions.py      # Feature-specific errors
+│   └── tests/
+├── billing/
+│   └── ...                # Same structure per feature
+├── shared/
+│   ├── config.py          # Pydantic BaseSettings
+│   ├── database.py        # Session factory, Base model
+│   ├── middleware.py       # CORS, logging, request tracing
+│   └── exceptions.py      # Application-wide exception base classes
+└── main.py                # App factory, router registration
+```
+
+Not every feature needs every file. A simple CRUD feature might have only `router.py`, `schemas.py`, and `service.py`. A complex domain feature might add `domain.py`, `events.py`, `repository.py`. Let complexity emerge per-slice.
+
+**Key pattern:** Routers delegate to service functions. Services import only their own feature's models and schemas. Wire features in the app factory via `app.include_router()`.
+
+## Inter-feature communication
+
+Four patterns, ordered by coupling (tightest to loosest):
+
+| Pattern | When to use | Example |
+|---------|-------------|---------|
+| **Direct service import** | Read-only access, simple projects, <5 features | `from src.auth.service import get_user` |
+| **FastAPI Depends()** | Request-scoped shared state, auth context | `user = Depends(get_current_user)` |
+| **Shared read models** | Cross-feature queries without write coupling | Database VIEWs mapped to read-only ORM classes |
+| **Events (pub/sub)** | Fire-and-forget: emails, analytics, indexing | `BackgroundTasks`, blinker `send_async()`, or task queue |
+
+**Default to direct service imports** for small projects. Introduce events only when features genuinely don't need synchronous responses. Don't build event infrastructure speculatively.
+
+**Batch service calls to avoid N+1.** When a feature lists entities that reference another feature's data, always provide a batch method alongside the single-item method:
+
+```python
+# src/auth/service.py
+async def get_users_by_ids(user_ids: list[int]) -> dict[int, User]:
+    """Batch fetch — single query with WHERE id IN (...)."""
+    async with get_session() as session:
+        stmt = select(User).where(User.id.in_(user_ids))
+        result = await session.execute(stmt)
+        return {u.id: u for u in result.scalars().all()}
+```
+
+```python
+# src/billing/service.py — WRONG: N+1 service calls
+async def list_invoices_with_users() -> list[InvoiceDetail]:
+    invoices = await get_invoices()
+    return [
+        InvoiceDetail(invoice=inv, user_name=(await get_user_by_id(inv.user_id)).name)
+        for inv in invoices  # 1 query per invoice
+    ]
+
+# RIGHT: batch fetch — 2 queries total regardless of N
+async def list_invoices_with_users() -> list[InvoiceDetail]:
+    invoices = await get_invoices()
+    users_map = await get_users_by_ids(list({inv.user_id for inv in invoices}))
+    return [
+        InvoiceDetail(invoice=inv, user_name=users_map[inv.user_id].name)
+        for inv in invoices
+    ]
+```
+
+**FastAPI dependency injection** for cross-feature auth context: define `get_current_user` in `src/auth/dependencies.py`, then inject via `Depends(get_current_user)` in other features' routers. Features import only `dependencies.py`, never auth internals.
+
+**Event-driven decoupling** when synchronous coupling is unacceptable:
+
+| Mechanism | Latency coupling | When to use |
+|-----------|-----------------|-------------|
+| `blinker send_async()` | Awaits all receivers | Receivers are fast, <50ms each |
+| `BackgroundTasks` | None — runs post-response | Side effects the caller doesn't wait for |
+| Task queue (Celery, ARQ) | None — separate worker | Retries, persistence, or heavy processing needed |
+
+Prefer `BackgroundTasks` for simple fire-and-forget (emails, analytics). Use `blinker` signals only when you need a publish/subscribe pattern with multiple listeners. Note: `send_async()` still awaits all receivers — it's async but not decoupled. For true fire-and-forget, use `BackgroundTasks` or a task queue.
+
+## Database model ownership
+
+The hardest problem in feature-driven architecture. Three strategies:
+
+| Strategy | Tradeoff | When to use |
+|----------|----------|-------------|
+| **Feature-private models** | Full isolation, no cross-feature FKs | Distinct data domains (auth, notifications) |
+| **ID-based references** | Loses referential integrity, risks N+1 | Features that reference but don't own shared data |
+| **Shared read layer** | Adds a shared dependency, but read-only | Heavy cross-feature reporting/querying |
+
+Feature-private models (preferred) — use plain `int` for cross-feature IDs, never `ForeignKey`:
+
+```python
+# src/billing/models.py
+class Invoice(Base):
+    __tablename__ = "invoices"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column()  # plain int, NOT ForeignKey("users.id")
+    amount: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+```
+
+For reporting that needs JOINs across feature boundaries, use database VIEWs with a write-protection mixin:
+
+```python
+# src/shared/read_models.py
+class ReadOnlyModel:
+    """Mixin — prevents accidental writes to VIEW-backed models."""
+    pass
+
+@event.listens_for(Session, "before_flush")
+def _prevent_readonly_flush(session, flush_context, instances):
+    for obj in session.new | session.dirty | session.deleted:
+        if isinstance(obj, ReadOnlyModel):
+            raise RuntimeError(f"Attempted to write to read-only model {type(obj).__name__}")
+
+class InvoiceWithUser(ReadOnlyModel, Base):
+    __tablename__ = "v_invoices_with_users"  # database VIEW, not a table
+    id: Mapped[int] = mapped_column(primary_key=True)
+    amount: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+    user_email: Mapped[str]
+```
+
+Create the VIEW in an Alembic migration with `op.execute("CREATE VIEW ...")` / `op.execute("DROP VIEW ...")`.
+
+## Migration ownership
+
+When features own their models, someone must own the migration files. Two practical strategies:
+
+**Strategy A: Centralized migrations (start here).** Single `alembic/versions/` directory. Any developer runs `alembic revision --autogenerate`. Simple, linear history, easy CI. Tradeoff: merge conflicts when multiple teams change models simultaneously. Use when team size <5.
+
+**Strategy B: Per-feature directories with branch labels.** Alembic supports `version_locations` for multiple migration directories. Each feature gets a branch label (`--head=base --branch-label=auth --version-path=src/auth/migrations`). Apply all branches with `alembic upgrade heads` (plural). Tradeoff: `autogenerate` cannot auto-detect which feature a model change belongs to. Use when 5+ developers and merge conflicts are frequent.
+
+For strongest isolation (approaching microservice extraction), each feature can use its own PostgreSQL schema — but this has significant infrastructure overhead and is rarely needed.
+
+**CI guard for all strategies:** Always run `alembic upgrade heads` against an empty database in CI.
+
+## Cross-feature testing
+
+Layered testing strategy — per-slice unit tests are straightforward; cross-feature integration is where teams get stuck.
+
+```
+tests/
+    conftest.py                # Shared factory fixtures (db_session, make_user, make_invoice)
+    features/
+        auth/
+            conftest.py        # Auth-specific fakes and helpers
+            test_service.py    # Unit: test with fakes
+        billing/
+            conftest.py
+            test_service.py
+    integration/
+        test_billing_auth.py   # Integration: billing + auth, real DB
+    workflows/
+        test_purchase_flow.py  # E2E: full request chain via test client
+```
+
+**Layer 1: Unit tests with fakes** (per feature, fast). Each feature tests its service layer in isolation:
+
+```python
+# tests/features/billing/test_service.py
+class FakeUserService:
+    def __init__(self, users: dict[int, User] | None = None):
+        self._users = users or {}
+
+    async def get_users_by_ids(self, user_ids: list[int]) -> dict[int, User]:
+        return {uid: self._users[uid] for uid in user_ids if uid in self._users}
+
+async def test_list_invoices_includes_user_names(db_session):
+    fake_users = FakeUserService(users={1: User(id=1, name="Alice")})
+    svc = BillingService(session=db_session, user_service=fake_users)
+    invoices = await svc.list_invoices_with_users()
+    assert invoices[0].user_name == "Alice"
+```
+
+**Layer 2: Integration tests with factory fixtures** (cross-feature, real DB). Shared factory fixtures in root `conftest.py` create real domain objects:
+
+```python
+# tests/conftest.py
+@pytest.fixture
+def make_user(db_session):
+    async def _make(email="test@example.com", **kwargs):
+        user = User(email=email, **kwargs)
+        db_session.add(user)
+        await db_session.flush()
+        return user
+    return _make
+```
+
+**Layer 3: Workflow tests** (E2E, real HTTP). Test full request chains through multiple features using the FastAPI test client. Keep these minimal — they're slow and brittle.
+
+**Key rules:**
+- Never import a feature's service directly from another feature's tests. Use factory fixtures or fakes.
+- Keep feature-specific fixtures in feature-level `conftest.py`. Only cross-feature factories go in root `conftest.py`.
+- Separate fast and slow tests with markers: `pytest -m "not integration"` for fast feedback, full suite in CI.
+- If using fakes, test them against the same contract as the real implementation to prevent drift.
+
+## Boundary enforcement
+
+**import-linter** — the minimum viable boundary enforcement. Add to `pyproject.toml`:
+
+```toml
+[tool.importlinter]
+root_package = "src"
+
+[[tool.importlinter.contracts]]
+name = "Features are independent"
+type = "independence"
+modules = [
+    "src.auth",
+    "src.billing",
+    "src.notifications",
+]
+
+[[tool.importlinter.contracts]]
+name = "Shared layer does not depend on features"
+type = "forbidden"
+source_modules = ["src.shared"]
+forbidden_modules = [
+    "src.auth",
+    "src.billing",
+    "src.notifications",
+]
+```
+
+Run in CI: `lint-imports`. Add as a pre-commit hook. Alternative: **PyTestArch** for teams that prefer executable architecture tests in pytest.
+
+**Exception to independence:** Features MAY import another feature's `dependencies.py` for FastAPI `Depends()` injection. Configure via `ignore_imports` in the independence contract:
+
+```toml
+ignore_imports = [
+    "src.billing.router -> src.auth.dependencies",
+    "src.notifications.router -> src.auth.dependencies",
+]
+```
+
+## When to use this pattern
+
+| Use when | Don't use when |
+|----------|----------------|
+| 5+ distinct business capabilities | Primarily CRUD with minimal logic |
+| 3+ developers with team ownership | 1-2 developers touching everything |
+| Features change independently | Codebase under 5,000 lines |
+| FastAPI or Flask project | Django with tight admin integration |
+| Incremental monolith migration | Features share data via complex JOINs |
+| Team comfortable with refactoring | Domain boundaries are unclear |
+
+## Migration from layered architecture
+
+Strangler Fig pattern — replace one feature at a time.
+
+**Phase 1: Map.** Identify which files change together. Those clusters are your features. Add integration tests for the first feature to migrate.
+
+**Phase 2: Extract shared.** Create `shared/` with cross-cutting concerns: database session factory, auth middleware, base model classes, response schemas.
+
+**Phase 3: Migrate one feature.** Pick the most isolated feature. Create a new package with router, schemas, service, and models. Wire alongside the old code. Verify with tests. Delete the old code.
+
+**Phase 4: Handle models.** Move models owned by a single feature into that feature's package. For shared models, decide: keep in `shared/data/`, or duplicate with ID-based references.
+
+**Phase 5: Handle migrations.** Start with centralized migrations (Strategy A). Graduate to per-feature branches (Strategy B) when merge conflicts become frequent.
+
+**Phase 6: Enforce.** Add import-linter contracts. Start descriptive, then tighten to enforced. Add to CI.
+
+**Phase 7: Iterate.** Apply Rule of Three for shared logic extraction. Decompose features exceeding ~1,500 lines of business logic. Add events for cross-feature triggers that don't need synchronous responses.
+
+## Anti-patterns
+
+- **Folder-only refactoring.** Moving files into feature directories without restructuring imports and dependencies. "Shuffling folders and calling it VSA" changes nothing.
+- **Premature abstraction.** Creating `IUserRepository`, `IOrderService` interfaces for one implementation. Python's Protocols provide structural typing where needed — don't add Java-style ceremony.
+- **Per-endpoint slicing.** Creating a directory for every single endpoint (`create_user/`, `get_user/`, `delete_user/`). This mirrors .NET MediatR patterns but is not idiomatic Python. Group by feature, not by operation.
+- **Event bus for everything.** Building event infrastructure before you have a single cross-feature trigger that doesn't need a synchronous response. Direct service calls are simpler and debuggable.
+- **God feature.** One slice absorbs most business logic. Start with procedural service functions, extract domain classes only when complexity warrants it.
+- **Shared model coupling.** Putting all ORM models in a central `models/` directory "for convenience." This recreates the layered architecture you were trying to escape.
+- **DRY over independence.** Extracting shared utilities after seeing the same pattern in two features. Wait for three. Duplication is cheaper than the wrong abstraction.
+- **N+1 service calls.** Calling `get_user_by_id` in a loop instead of `get_users_by_ids` with `WHERE id IN (...)`. Always provide batch methods for cross-feature data access.
+- **Synchronous side effects in signal handlers.** Using blinker `send()` with I/O listeners — this blocks the caller. Use `BackgroundTasks` or a task queue.