Imported from yonatangross/orchestkit (src/skills/architecture-patterns/SKILL.md). Install upstream with npx skills add yonatangross/orchestkit --skill architecture-patterns. Copyright stays with the author (MIT).

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: checklists/solid-checklist.md. Domain entity scaffold: 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): 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("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