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 references/ loaded on-demand.

Quick Reference

Category Rules Impact When to Use

Clean Architecture 3 HIGH SOLID principles, hexagonal architecture, ports & adapters, DDD

Project Structure 2 HIGH Folder conventions, nesting depth, import direction, barrel files

Backend Layers 3 HIGH Router/service/repository separation, DI, file naming

Test Standards 3 MEDIUM AAA pattern, naming conventions, coverage thresholds

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 ${CLAUDE_SKILL_DIR}/references/clean-hexagonal-ports-adapters.md

Driving/driven ports, adapter implementations, layer structure

SOLID & Dependency Rule ${CLAUDE_SKILL_DIR}/references/clean-solid-dependency-rule.md

Protocol-based interfaces, dependency inversion, FastAPI DI

DDD Tactical Patterns ${CLAUDE_SKILL_DIR}/references/clean-ddd-tactical-patterns.md

Entities, value objects, aggregate roots, domain events

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 ${CLAUDE_SKILL_DIR}/references/structure-folder-conventions.md

React/Next.js and FastAPI layouts, 4-level max nesting, barrel file rules

Import Direction & Location ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/references/backend-layer-separation.md

Router/service/repository boundaries, forbidden patterns, async rules

Dependency Injection ${CLAUDE_SKILL_DIR}/references/backend-dependency-injection.md

Depends() chains, auth patterns, testing with DI overrides

File Naming & Exceptions ${CLAUDE_SKILL_DIR}/references/backend-naming-exceptions.md

Naming conventions, domain exceptions, violation detection

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 File Key Pattern

AAA Pattern & Isolation ${CLAUDE_SKILL_DIR}/references/testing-aaa-isolation.md

Arrange-Act-Assert, test isolation, parameterized tests

Naming Conventions ${CLAUDE_SKILL_DIR}/references/testing-naming-conventions.md

Descriptive behavior-focused names for Python and TypeScript

Coverage & Location ${CLAUDE_SKILL_DIR}/references/testing-coverage-location.md

Coverage thresholds, fixture scopes, test file placement rules

Coverage Requirements

Area Minimum Target

Overall 80% 90%

Business Logic 90% 100%

Critical Paths 95% 100%

New Code 100% 100%

Right-Sizing

Context-aware backend architecture enforcement. Rules adjust strictness based on project tier detected by scope-appropriate-architecture .

Enforcement procedure:

• Read project tier from scope-appropriate-architecture context (set during brainstorm/implement Step 0)

• If no tier set, auto-detect using signals in Read("${CLAUDE_SKILL_DIR}/rules/right-sizing-tiers.md")

• Apply tier-based enforcement matrix — skip rules marked OFF for detected tier

• Security rules are tier-independent — always enforce SQL parameterization, input validation, auth checks

Rule File Key Pattern

Architecture Sizing Tiers ${CLAUDE_SKILL_DIR}/rules/right-sizing-tiers.md

Interview/MVP/production/enterprise sizing matrix, LOC estimates, detection signals

Right-Sizing Decision Guide ${CLAUDE_SKILL_DIR}/rules/right-sizing-decision.md

ORM, auth, error handling, testing recommendations per tier, over-engineering tax

Tier-Based Rule Enforcement

Rule Interview MVP Production Enterprise

Layer separation OFF WARN BLOCK BLOCK

Repository pattern OFF OFF WARN BLOCK

Domain exceptions OFF OFF BLOCK BLOCK

Dependency injection OFF WARN BLOCK BLOCK

OpenAPI documentation OFF OFF WARN BLOCK

Manual override: User can set tier explicitly to bypass auto-detection (e.g., "I want enterprise patterns for this take-home to demonstrate skill").

Decision Flowchart

Is this a take-home or hackathon? YES --> Flat architecture. Single file or 3-5 files. Done. NO -->

Is this a prototype or MVP with < 3 months runway? YES --> Simple layered. Routes + services + models. No abstractions. NO -->

Do you have > 5 engineers or complex domain rules? YES --> Clean architecture with ports/adapters. NO --> Layered architecture. Add abstractions only when pain appears.

When NOT to Use

Not every project needs architecture patterns. Match complexity to project tier:

Pattern Interview Hackathon MVP Growth Enterprise Simpler Alternative

Repository pattern OVERKILL (~200 LOC) OVERKILL BORDERLINE APPROPRIATE REQUIRED Direct ORM calls in service (~20 LOC)

DI containers OVERKILL (~150 LOC) OVERKILL LIGHT ONLY APPROPRIATE REQUIRED Constructor params or module-level singletons (~10 LOC)

Event-driven arch OVERKILL (~300 LOC) OVERKILL OVERKILL SELECTIVE APPROPRIATE Direct function calls between services (~30 LOC)

Hexagonal architecture OVERKILL (~400 LOC) OVERKILL OVERKILL BORDERLINE APPROPRIATE Flat modules with imports (~50 LOC)

Strict layer separation OVERKILL (~250 LOC) OVERKILL WARN BLOCK BLOCK Routes + models in same file (~40 LOC)

Domain exceptions OVERKILL (~100 LOC) OVERKILL OVERKILL BLOCK BLOCK Built-in ValueError/HTTPException (~5 LOC)

Rule of thumb: If a pattern shows OVERKILL for the detected tier, do NOT use it. Use the simpler alternative. A take-home with hexagonal architecture signals over-engineering, not skill.

Anti-Patterns (FORBIDDEN)

CLEAN ARCHITECTURE

NEVER import infrastructure in domain layer

from app.infrastructure.database import engine # In domain layer!

NEVER leak ORM models to API layer

@router.get("/users/{id}") async def get_user(id: str, db: Session) -> UserModel: # Returns ORM model!

NEVER have domain depend on framework

from fastapi import HTTPException class UserService: def get(self, id: str): raise HTTPException(404) # Framework in domain!

PROJECT STRUCTURE

NEVER create files deeper than 4 levels from src/

NEVER create barrel files (index.ts re-exports)

NEVER import from higher layers (features importing from app)

NEVER import across features (use shared/ for common code)

BACKEND LAYERS

NEVER use database operations in routers

NEVER raise HTTPException in services

NEVER instantiate services without Depends()

TEST STANDARDS

NEVER mix test files with source code

NEVER use non-descriptive test names (test1, test, works)

NEVER share mutable state between tests without reset

Related Skills

• ork:scope-appropriate-architecture

• Project tier detection that drives right-sizing enforcement

• ork:quality-gates

• YAGNI gate uses tier context to validate complexity

• ork:distributed-systems

• Distributed locking, resilience, idempotency patterns

• ork:api-design

• REST API design, versioning, error handling

• ork:testing-unit

• Unit testing: AAA pattern, fixtures, mocking, factories

• ork:testing-e2e

• E2E testing: Playwright, page objects, visual regression

• ork:testing-integration

• Integration testing: API endpoints, database, contracts

• ork:python-backend

• FastAPI, SQLAlchemy, asyncio patterns

• ork:database-patterns

• Schema design, query optimization, migrations