/architecture-patterns

name: architecture-patterns
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Clean and layered architecture patterns, project structure and test-standard validation. Use when designing system boundaries or enforcing structure. For tier sizing, use scope-appropriate-architecture."
skills: [scope-appropriate-architecture]
user-invocable: false
disable-model-invocation: false
effort: high
metadata:
  owner-agent: "backend-system-architect"
  category: document-asset-creation
  version: "2.1.0"
  author: "OrchestKit"
  complexity: "high"
  tags: "architecture, clean-architecture, validation, structure, enforcement, testing-standards, right-sizing, over-engineering, context-aware"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
paths: ["src/**", "package.json", "tsconfig.json"]

<!-- directive-density: intentional (teaches anti-patterns; NEVER markers describe real layering violations, not aspirational guidance) -->

Architecture Patterns

Consolidated architecture validation and enforcement patterns covering clean architecture, backend layer separation, project structure conventions, and test standards. Each category has individual rule files in `rules/` loaded on-demand. House scars and dated decisions rescued from retired reference tutorials live in `references/ork-delta.md`; the tutorials themselves are upstream's job (see "Upstream coverage" below).

Quick Reference

| Category | Rules | Impact | When to Use | |----------|-------|--------|-------------| | [Clean Architecture](#clean-architecture) | 3 | HIGH | SOLID principles, hexagonal architecture, ports & adapters, DDD | | [Project Structure](#project-structure) | 2 | HIGH | Folder conventions, nesting depth, import direction, barrel files | | [Backend Layers](#backend-layers) | 3 | HIGH | Router/service/repository separation, DI, file naming | | [Test Standards](#test-standards) | 3 | MEDIUM | AAA pattern, naming conventions, coverage thresholds | | [Right-Sizing](#right-sizing) | 2 | HIGH | Architecture tier selection, over-engineering prevention, context-aware enforcement |

**Total: 13 rules across 5 categories**

Quick Start

# Clean Architecture: Dependency Inversion via Protocol
class IUserRepository(Protocol):
    async def get_by_id(self, id: str) -> User | None: ...

class UserService:
    def __init__(self, repo: IUserRepository):
        self._repo = repo  # Depends on abstraction, not concretion

# FastAPI DI chain: DB -> Repository -> Service
def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
    return UserService(PostgresUserRepository(db))

# Project Structure: Unidirectional Import Architecture
shared/lib  ->  components  ->  features  ->  app
(lowest)                                    (highest)

# Backend Layers: Strict Separation
Routers (HTTP) -> Services (Business Logic) -> Repositories (Data Access)

Clean Architecture

SOLID principles, hexagonal architecture, ports and adapters, and DDD tactical patterns for maintainable backends.

| Rule | File | Key Pattern | |------|------|-------------| | Hexagonal Architecture | `rules/clean-hexagonal.md` | Driving/driven ports, adapter implementations, layer structure | | SOLID & Dependency Rule | `rules/clean-dependency-rule.md` | Protocol-based interfaces, dependency inversion, FastAPI DI | | DDD Tactical Patterns | `rules/clean-ports-adapters.md` | Entities, value objects, aggregate roots, domain events |

Design review checklist: `checklists/solid-checklist.md`. Domain entity scaffold: `scripts/domain-entity-template.py`.

Key Decisions

| Decision | Recommendation | |----------|----------------| | Protocol vs ABC | Protocol (structural typing) | | Dataclass vs Pydantic | Dataclass for domain, Pydantic for API | | Repository granularity | One per aggregate root | | Transaction boundary | Service layer, not repository | | Event publishing | Collect in aggregate, publish after commit |

Project Structure

Feature-based organization, max nesting depth, unidirectional imports, and barrel file prevention.

| Rule | File | Key Pattern | |------|------|-------------| | Folder Structure & Nesting | `rules/structure-folders.md` | React/Next.js and FastAPI layouts, 4-level max nesting, barrel file rules | | Import Direction & Location | `references/structure-import-direction.md` | Unidirectional imports, cross-feature prevention, component/hook placement |

Blocking Rules

| Rule | Check | |------|-------| | Max Nesting | Max 4 levels from src/ or app/ | | No Barrel Files | No index.ts re-exports (tree-shaking issues) | | Component Location | React components in components/ or features/ only | | Hook Location | Custom hooks in hooks/ or features/*/hooks/ only | | Import Direction | Unidirectional: shared -> components -> features -> app |

Backend Layers

FastAPI Clean Architecture with router/service/repository layer separation and blocking validation.

| Rule | File | Key Pattern | |------|------|-------------| | Layer Separation | `rules/backend-layers.md` | Router/service/repository boundaries, forbidden patterns, async rules | | Dependency Injection | `rules/backend-di.md` | Depends() chains, blocked DI patterns, violation detection | | File Naming & Exceptions | `rules/backend-repository.md` | Naming conventions, async rules, domain exceptions |

House scars for this category (exception-to-HTTP status map, import-level violation greps, DI override teardown): `references/ork-delta.md`.

Layer Boundaries

| Layer | Responsibility | Forbidden | |-------|---------------|-----------| | Routers | HTTP concerns, request parsing, auth checks | Database operations, business logic | | Services | Business logic, validation, orchestration | HTTPException, Request objects | | Repositories | Data access, queries, persistence | HTTP concerns, business logic |

Test Standards

Testing best practices with AAA pattern, naming conventions, isolation, and coverage thresholds.

| Rule | F