Scope Appropriate Architecture

Scope-Appropriate Architecture

Right-size every architectural decision to the project's actual needs. Not every project needs hexagonal architecture, CQRS, or microservices.

Core principle: Detect the project tier first, then constrain all downstream pattern choices to that tier's complexity ceiling.

---

The 6 Project Tiers

LOC Ratio = total lines / core business logic lines. Higher ratio = more infrastructure code relative to business value.

---

Auto-Detection Signals

When confidence is low: Ask the user with AskUserQuestion.

---

Pattern Appropriateness Matrix

Rule of thumb: If a pattern shows OVERKILL for the detected tier, do NOT use it. Suggest the simpler alternative instead.

---

Technology Quick-Reference by Tier

---

Build vs Buy Decision Tree (Tiers 1-3)

For Interview, Hackathon, and MVP tiers, always prefer buying over building:

Time savings: Auth alone is 2-4 weeks build vs 2 hours integrate.

---

Upgrade Path

When a project grows beyond its current tier, upgrade incrementally:

Tier 2 (Prototype) → Tier 3 (MVP)
  Add: Postgres, basic auth, error boundaries, CI

Tier 3 (MVP) → Tier 4 (Growth)
  Add: Redis cache, background jobs, monitoring, module boundaries

Tier 4 (Growth) → Tier 5 (Enterprise)
  Add: DI, bounded contexts, message queues, full observability
  Extract: First microservice (only the proven bottleneck)

Key insight: You can always add complexity later. You cannot easily remove it.

---

When This Skill Activates

This skill is loaded by:

• brainstorm Phase 0 (context discovery)
• implement Step 0 (context discovery)
• quality-gates YAGNI check
• Any skill that needs to right-size a recommendation

The detected tier is passed as context to constrain downstream decisions.

---

Related Skills

• ork:brainstorm - Uses tier detection in Phase 0 to constrain ideas
• ork:implement - Uses tier detection in Step 0 to constrain architecture
• ork:quality-gates - YAGNI gate references this skill's tier matrix
• ork:architecture-patterns - Architecture validation (constrained by tier)

---

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

Enterprise Guide (Tiers 4-5)

Guidance for growth-stage and enterprise production applications.

Tier 4: Growth-Stage

When You're Here

• 4-15 developers on the codebase
• $10K-$500K MRR
• 10K-1M monthly active users
• SLAs exist (99.5%+ uptime)
• Compliance requirements emerging

Architecture: Modular Monolith

src/
├── modules/
│   ├── users/
│   │   ├── api/            # Module-scoped routes
│   │   ├── services/       # Business logic
│   │   ├── repository/     # Data access (NOW justified)
│   │   └── types/          # Module types
│   ├── orders/
│   │   ├── api/
│   │   ├── services/
│   │   ├── repository/
│   │   └── types/
│   └── shared/             # Cross-module utilities
├── infrastructure/
│   ├── database/           # Connection, migrations
│   ├── cache/              # Redis client
│   ├── queue/              # Background job client
│   └── monitoring/         # APM setup
└── config/                 # Environment-specific config

Patterns NOW Justified

Patterns Still OVERKILL

Database at Growth Stage

• Primary: Postgres with connection pooling (PgBouncer or managed)
• Cache: Redis for sessions, hot data, rate limiting
• Background: Redis-backed queue (BullMQ, Celery)
• Search: Postgres full-text or Typesense (if > 100K searchable records)

Testing Strategy

---

Tier 5: Enterprise

When You're Here

• 15+ developers, multiple teams
• $500K+ MRR or enterprise contracts
• 1M+ monthly active users
• Strict SLAs (99.9%+ uptime)
• Compliance: SOC2, HIPAA, GDPR, or similar
• Incidents cost real money

Architecture: Domain-Driven (Hexagonal)

src/
├── domains/
│   ├── identity/           # Bounded context
│   │   ├── application/    # Use cases, commands, queries
│   │   ├── domain/         # Entities, value objects, events
│   │   ├── infrastructure/ # Repos, adapters, external services
│   │   └── presentation/   # Controllers, DTOs, serializers
│   ├── billing/
│   │   └── ...
│   └── catalog/
│       └── ...
├── shared/
│   ├── kernel/             # Shared value objects, base classes
│   └── infrastructure/     # Cross-cutting: auth, logging, tracing
├── api-gateway/            # Route to domains
└── workers/                # Background processors per domain

Patterns NOW Justified

Justification Required

Even at enterprise scale, these patterns need specific justification:

Database at Enterprise Scale

• Primary: Postgres with read replicas, connection pooling
• Cache: Redis Cluster (HA) or Valkey
• Queue: RabbitMQ or Kafka (based on throughput needs)
• Search: Elasticsearch or OpenSearch (> 1M documents)
• Analytics: Data warehouse (BigQuery, Snowflake, ClickHouse)

Monitoring & Observability

Testing Strategy

Interview & Take-Home Guide (Tiers 1-2)

Guidance for interview assignments, take-home projects, hackathons, and prototypes.

Tier 1: Interview / Take-Home

Target Metrics

What Interviewers Actually Evaluate

1. Clean, readable code — not architectural patterns 2. Working solution — not infrastructure 3. Good naming and structure — not abstractions 4. Thoughtful trade-offs — documented, not implemented 5. Tests for critical paths — not 100% coverage

Architecture Pattern

src/
├── app.ts              # Entry point + routes
├── handlers/           # Request handlers (thin)
├── services/           # Business logic (1-2 files)
├── types.ts            # Shared types
└── __tests__/          # Co-located tests

No repository pattern. No DI. No separate DTO layers. No middleware chain.

Highest-Leverage Technique

Add a "What I Would Change for Production" section to README:

## What I Would Change for Production

- **Database**: Replace SQLite with Postgres + connection pooling
- **Auth**: Integrate Clerk/Auth0 instead of basic token
- **Error handling**: Add structured error responses (RFC 9457)
- **Monitoring**: Add OpenTelemetry tracing
- **Testing**: Add integration tests with testcontainers
- **CI/CD**: Add GitHub Actions with lint, test, build stages

This shows awareness WITHOUT building it. Interviewers value judgment over implementation.

Common Over-Engineering Mistakes

What TO Build

• Clear input validation with helpful error messages
• One integration test that proves the happy path works
• A few unit tests for edge cases in business logic
• Clean README with setup instructions (< 5 steps)

---

Tier 2: Hackathon / Prototype

Target Metrics

Architecture Pattern

Single file if possible. Maximum one level of extraction.

app.ts          # Everything
# OR
app.ts          # Routes + handlers
db.ts           # Data access

Principles

• Ship the demo. Nothing else matters.
• Hardcode everything. Config is waste.
• No tests. Prototype will be thrown away.
• Use the highest-level abstractions available. ORMs, UI kits, SaaS APIs.
• Copy-paste is fine. DRY is for production code.

Technology Choices

• Framework: Whatever you know best
• Database: SQLite, JSON file, or in-memory
• Deployment: Vercel, Railway, or localhost
• Auth: Hardcoded user or none
• UI: Tailwind + shadcn/ui (fastest to good-looking)

Open Source Guide (Tier 6)

Guidance for open-source libraries, frameworks, and tools.

Target Metrics

Architecture Principles

1. Minimal API Surface

Expose the minimum necessary. Everything public becomes a contract.

// Good: Small, focused API
export { createClient } from "./client";
export type { ClientOptions, Client } from "./types";

// Bad: Leaking internals
export { createClient, _parseResponse, _buildUrl, _retryWithBackoff } from "./client";

2. Zero or Minimal Dependencies

Every dependency is a liability for consumers:

• Security vulnerabilities propagate
• Version conflicts with consumer's dependencies
• Bundle size increases
• Maintenance burden when deps are abandoned

Prefer: Vendoring small utilities over adding dependencies.

3. Backwards Compatibility

• Semantic versioning is non-negotiable
• Deprecate before removing (minimum 1 minor version)
• Migration guides for every breaking change
• Codemods when feasible (like Next.js does)

Testing Strategy

Test What Matters

// Test public API behavior, not implementation details
test("createClient returns working client", () => {
  const client = createClient({ apiKey: "test" });
  expect(client.query).toBeDefined();
  expect(typeof client.query).toBe("function");
});

// Test edge cases consumers will hit
test("createClient throws on missing apiKey", () => {
  expect(() => createClient({})).toThrow("apiKey is required");
});

Documentation

What Makes Open Source Different

Common Mistakes

Package Structure Decisions

Startup & MVP Guide (Tier 3)

Guidance for MVPs, early-stage startups, and small production applications.

Target Metrics

Architecture: MVC Monolith

src/
├── app/                    # Next.js App Router pages
│   ├── api/                # API routes (thin handlers)
│   ├── (auth)/             # Auth-gated pages
│   └── (public)/           # Public pages
├── lib/
│   ├── db.ts               # Database client (Drizzle/Prisma)
│   ├── auth.ts             # Auth config (Clerk/Supabase)
│   └── email.ts            # Email client (Resend)
├── components/             # React components
├── actions/                # Server actions (business logic)
└── types/                  # Shared types

Key Principles

1. Monolith first. Always. No exceptions. 2. Managed services. Database, auth, email, storage — all SaaS. 3. One deployment target. Vercel OR Railway, not both. 4. Feature flags over branches. Ship incomplete features behind flags. 5. Server actions over API routes. Less boilerplate, same safety.

Build vs Buy at MVP Scale

Total potential savings: 12-24 weeks by choosing BUY for non-core features.

Database Decisions

• Default choice: Managed Postgres (Supabase, Neon, Railway)
• ORM: Drizzle (type-safe, lightweight) or Prisma (broader ecosystem)
• Migrations: ORM-managed, not manual SQL
• Caching: None initially. Add Redis only after measuring bottlenecks.

What NOT to Do

• No read replicas (you don't have the traffic)
• No database-per-service (you have one service)
• No custom connection pooling (managed service handles it)
• No event sourcing (your audit needs are met by updated_at columns)

Testing Strategy

Rule: Test the user flows that lose you money if broken. Skip everything else.

Error Handling

// MVP-appropriate error handling
try {
  const result = await createOrder(data);
  return { success: true, data: result };
} catch (error) {
  console.error("Order creation failed:", error);
  return { success: false, error: "Failed to create order" };
}

No custom error hierarchies. No error codes. No RFC 9457. Log it, return a message, move on.

Deployment

• Platform: Vercel (frontend-heavy) or Railway (backend-heavy)
• CI/CD: GitHub Actions — lint + test + deploy (3 steps max)
• Environments: Production + Preview (Vercel auto). No staging.
• Monitoring: Error tracking (Sentry free tier) + uptime (Better Stack free)

When to Upgrade to Tier 4

Upgrade when you have evidence, not speculation:

Rule Categories

1. Tier Detection (evidence) — HIGH — 1 rule

Requires codebase evidence for every tier signal to prevent wrong-tier detection from cascading into all downstream architecture decisions.

• tier-detection-evidence.md — Cite at least 3 signals from different categories, each referencing a specific file or metric, before assigning a tier

2. Over-Engineering Prevention (yagni) — HIGH — 1 rule

Flags patterns that are rated OVERKILL for the current tier and appropriate only 2+ tiers higher, requiring explicit user justification to proceed.

• over-engineering-flag.md — Apply the Tier + 2 Rule: flag any pattern appropriate only at current tier + 2 or higher and suggest the tier-appropriate alternative

3. Deferred-Debt Tracking (yagni) — MEDIUM — 1 rule

Records the deliberate under-engineering chosen to fit the current tier — the counterpart to over-engineering prevention — so each cut resurfaces when the condition that should trigger its upgrade is met.

• deferred-debt-marker.md — Mark deliberate simplifications with // ork-debt: <choice>, upgrade to <path>, when <trigger>; two hooks capture and surface the ledger automatically

Mark Deliberate Simplifications (Deferred-Debt Marker)

Why

The YAGNI gate and the Tier + 2 rule PREVENT over-engineering — they stop you building OAuth2+PKCE for a take-home or CQRS for a todo app. But once that correct, tier-appropriate decision is made, it disappears: the code shows the simple thing with no record that it was chosen, nor what should make you revisit it.

A deferred-debt marker is the counterpart. It records the deliberate under-engineering at the moment you choose it, together with the condition that should trigger the upgrade. It is NOT a TODO — the when <trigger> clause is what turns a forgettable note into a ledger entry that can tell you when to act.

Rule

When you deliberately pick a simpler implementation to fit the current tier, drop an inline marker on the line where the shortcut lives:

// ork-debt: <choice>, upgrade to <path>, when <trigger>

• <choice> — the deliberate simplification you made
• upgrade to <path> — what to switch to later (optional but recommended)
• when <trigger> — the condition that should make you revisit (optional, but

without it the marker degrades to a plain TODO)

The comment leader may be //, #, --, ;, or a block-comment leader, so the convention works across languages.

Correct — record the cut and its trigger

// ork-debt: session cookies, upgrade to JWT + refresh tokens, when a 2nd service is added
const session = signCookie(userId);

# ork-debt: SQLite single-file, upgrade to Postgres, when concurrent writers > 1
db = sqlite3.connect("./app.db")

Incorrect — the cut with no trace, or a bare TODO

// TODO: maybe use a real DB later
const session = signCookie(userId);

Problems:

• No record that the simple choice was deliberate (vs an oversight)
• No upgrade path — the next engineer re-derives it from scratch
• No trigger — nothing tells you when the cut stops being appropriate

How it surfaces (automatic, no manual command)

Two hooks maintain the ledger for you in the background:

• posttool/write/debt-marker-tracker confirms capture the moment you write a

marker.

• instructions-loaded/debt-surfacer greps the repo and injects a compact

ledger summary into context at session start.

Opt out per hook with ORK_DISABLE_DEBT_TRACKER=1 / ORK_DISABLE_DEBT_SURFACER=1.

Relationship to other rules

• over-engineering-flag.md — flags building too much for the tier (prevent)
• tier-detection-evidence.md — establishes the tier this cut is scoped to
• this rule — records the deliberate too-little, so it is revisitable (record)

Flag Over-Engineering (Tier + 2 Rule)

Why

A pattern appropriate at Tier 5 (Enterprise) adds weeks of development time to a Tier 2 (Hackathon). The complexity does not pay for itself until the project reaches the tier where it is needed. The "Tier + 2 Rule" catches patterns that are 2+ levels above the detected tier.

Rule

After detecting the project tier: 1. Check each proposed pattern against the Pattern Appropriateness Matrix 2. If a pattern is rated OVERKILL for the current tier AND the tier where it becomes APPROPRIATE is 2+ levels higher, flag it 3. Suggest the tier-appropriate alternative 4. Only allow override with explicit user justification

Incorrect — recommend enterprise patterns for a prototype

## Architecture for Todo App (Tier 2: Hackathon)

### Recommended:
- Hexagonal architecture with ports and adapters
- CQRS with separate read/write models
- Event sourcing for audit trail
- Dependency injection container (tsyringe)
- Separate DTO/Entity/Domain layers
- Message queue for async operations

Problems:

• Hexagonal is Tier 5 (3 levels above Tier 2)
• CQRS is Tier 5 (3 levels above)
• Event sourcing is Tier 5 (3 levels above)
• DI container is Tier 4 (2 levels above)
• A Todo app needs none of this

Correct — flag over-engineering with tier-appropriate alternatives

## Architecture for Todo App (Tier 2: Hackathon)

### OVER-ENGINEERING FLAGS:

| Proposed Pattern | Appropriate At | Current Tier | Gap | Alternative |
|-----------------|---------------|--------------|-----|-------------|
| Hexagonal architecture | Tier 5 | Tier 2 | +3 | Flat file structure |
| CQRS | Tier 5 | Tier 2 | +3 | Single model |
| Event sourcing | Tier 5 | Tier 2 | +3 | Simple CRUD |
| DI container | Tier 4 | Tier 2 | +2 | Direct imports |

### Recommended (Tier 2 appropriate):
- Single file or flat structure
- Direct function calls, no DI
- SQLite or in-memory storage
- No layers — route handler calls DB directly

Pattern Check Implementation

const PATTERN_TIER: Record<string, number> = {
  "hexagonal":        5,
  "cqrs":             5,
  "event-sourcing":   5,
  "ddd":              5,
  "di-container":     4,
  "message-queue":    4,
  "microservices":    5,
  "repository":       4,
  "separate-dtos":    4,
  "api-versioning":   3,
};

function checkOverEngineering(
  currentTier: number,
  proposedPatterns: string[]
): { pattern: string; gap: number; appropriateAt: number }[] {
  return proposedPatterns
    .map(p => ({
      pattern: p,
      appropriateAt: PATTERN_TIER[p] ?? currentTier,
      gap: (PATTERN_TIER[p] ?? currentTier) - currentTier
    }))
    .filter(p => p.gap >= 2);
}

// Example: Tier 2 project
const flags = checkOverEngineering(2, ["hexagonal", "cqrs", "api-versioning"]);
// flags = [
//   { pattern: "hexagonal", appropriateAt: 5, gap: 3 },
//   { pattern: "cqrs", appropriateAt: 5, gap: 3 }
// ]
// "api-versioning" (Tier 3, gap 1) is not flagged

When Override Is Acceptable

Flag but allow if the user provides explicit justification:

Tier Detection Must Cite Evidence

Why

The 6-tier system constrains all downstream architecture decisions. If tier detection is wrong, every recommendation is wrong: a hackathon gets CQRS, an enterprise app gets console.log. Tier must be derived from codebase evidence, not guesses.

Rule

When detecting project tier: 1. Scan for at least 3 signals from different categories 2. Each signal must reference a specific file or metric 3. If signals conflict, cite the conflict and ask the user 4. Never default to a tier without evidence

Incorrect — assume tier without evidence

## Architecture Recommendation

This looks like a startup MVP, so I recommend:
- MVC monolith
- Managed Postgres
- Clerk for auth
- Basic CI with GitHub Actions

Problems:

• "Looks like" is not evidence
• No files were checked
• No metrics were gathered
• If this is actually a Tier 5 enterprise app, every recommendation is wrong

Correct — cite evidence for tier detection

## Tier Detection: Tier 3 (Startup/MVP)

**Evidence (4 signals):**

| Signal | Source | Tier Indicated |
|--------|--------|----------------|
| 12 source files, no monorepo structure | `find src -name "*.ts" \| wc -l` = 12 | Tier 2-3 |
| GitHub Actions present, single workflow | `.github/workflows/ci.yml` exists | Tier 3+ |
| 8 direct dependencies | `package.json` dependencies count | Tier 2-3 |
| No Kubernetes, no Terraform | `find . -name "*.tf" -o -name "*.yaml" \| grep -l "kind: Deployment"` = empty | Not Tier 4-5 |

**Confidence:** HIGH (4/4 signals agree on Tier 2-3, CI presence upgrades to Tier 3)

**Recommendation:** Tier 3 (Startup/MVP) constraints apply.

Signal Categories

Scan at least one signal from each category:

# Category 1: Scale indicators
find src -name "*.ts" -o -name "*.py" | wc -l          # File count
wc -l src/**/*.ts 2>/dev/null | tail -1                 # Total LOC

# Category 2: Infrastructure signals
ls .github/workflows/ 2>/dev/null                       # CI presence
ls docker-compose* Dockerfile 2>/dev/null               # Container presence
find . -name "*.tf" -o -name "helmfile*" 2>/dev/null    # K8s/Terraform

# Category 3: Dependency complexity
cat package.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('dependencies',{})))"
ls CONTRIBUTING.md CODE_OF_CONDUCT.md 2>/dev/null        # OSS indicators

# Category 4: Documentation signals
grep -ril "take-home\|assignment\|interview" README* 2>/dev/null
grep -ril "enterprise\|compliance\|SOC2" README* docs/ 2>/dev/null

Conflict Resolution

When signals disagree:

## Tier Detection: CONFLICTING SIGNALS

| Signal | Tier Indicated |
|--------|----------------|
| 5 files, 200 LOC | Tier 1-2 |
| Kubernetes manifests present | Tier 4-5 |
| No tests | Tier 1-2 |

**Conflict:** Codebase size suggests prototype, but K8s manifests
suggest enterprise. Asking user to clarify project intent.

Do not average or guess — ask the user when signals conflict by more than 1 tier.