architecture-patterns

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

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.

Design review checklist: ${CLAUDE_PLUGIN_ROOT}/skills/architecture-patterns/checklists/solid-checklist.md. Domain entity scaffold: ${CLAUDE_PLUGIN_ROOT}/skills/architecture-patterns/scripts/domain-entity-template.py.

Key Decisions

Project Structure

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

Blocking Rules

Backend Layers

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

House scars for this category (exception-to-HTTP status map, import-level violation greps, DI override teardown): ${CLAUDE_PLUGIN_ROOT}/skills/architecture-patterns/references/ork-delta.md.

Layer Boundaries

Test Standards

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

Coverage Requirements

Right-Sizing

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

Enforcement procedure:

1. Read project tier from scope-appropriate-architecture context (set during brainstorm/implement Step 0)
2. If no tier set, auto-detect using signals in Read("${CLAUDE_PLUGIN_ROOT}/skills/architecture-patterns/rules/right-sizing-tiers.md")
3. Apply tier-based enforcement matrix — skip rules marked OFF for detected tier
4. Security rules are tier-independent — always enforce SQL parameterization, input validation, auth checks

Tier-Based Rule Enforcement

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:

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

Upstream coverage (do not restate)

Long-form tutorials on these topics were removed from this skill (2026-07-31 wrap-plus-delta campaign). Read them at the first-party source; only floors, scars, and house decisions belong here (see references/ork-delta.md).

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