scope-appropriate-architecture

What this skill does

# 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

| Tier | LOC Ratio | Architecture | DB | Auth | Tests |
|------|-----------|-------------|-----|------|-------|
| **1. Interview/Take-home** | 1.0-1.3x | Flat files, no layers | SQLite / JSON | None or basic | 8-15 focused |
| **2. Hackathon/Prototype** | 0.8-1.0x | Single file if possible | SQLite / in-memory | None | Zero |
| **3. Startup/MVP** | 1.0-1.5x | MVC monolith | Managed Postgres | Clerk/Supabase Auth | Happy path + critical |
| **4. Growth-stage** | 1.5-2.0x | Modular monolith | Postgres + Redis | Auth service | Unit + integration |
| **5. Enterprise** | 2.0-3.0x | Hexagonal/DDD | Postgres + queues | OAuth2/SAML | Full pyramid |
| **6. Open Source** | 1.2-1.8x | Minimal API surface | Configurable | Optional | Exhaustive public API |

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

---

## Auto-Detection Signals

| Signal | Tier Indicator |
|--------|---------------|
| README contains "take-home", "assignment", "interview" | Tier 1 |
| Time limit mentioned (e.g., "4 hours", "weekend") | Tier 1-2 |
| < 10 files, no CI, no Docker | Tier 1-2 |
| `.github/workflows/` present | Tier 3+ |
| `package.json` with 20+ dependencies | Tier 3+ |
| Kubernetes/Terraform files present | Tier 4-5 |
| `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` | Tier 6 |
| Monorepo with `packages/` or `apps/` | Tier 4-5 |

**When confidence is low:** Ask the user with `AskUserQuestion`.

---

## Pattern Appropriateness Matrix

| Pattern | Interview | Hackathon | MVP | Growth | Enterprise |
|---------|-----------|-----------|-----|--------|------------|
| Repository pattern | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE | REQUIRED |
| Event-driven arch | OVERKILL | OVERKILL | OVERKILL | SELECTIVE | APPROPRIATE |
| DI containers | OVERKILL | OVERKILL | LIGHT ONLY | APPROPRIATE | REQUIRED |
| Separate DTO layers | OVERKILL | OVERKILL | 1 EXTRA | 2 LAYERS | ALL LAYERS |
| Microservices | NEVER | NEVER | NEVER | EXTRACT ONLY | APPROPRIATE |
| CQRS | OVERKILL | OVERKILL | OVERKILL | OVERKILL | WHEN JUSTIFIED |
| Hexagonal architecture | OVERKILL | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE |
| DDD (bounded contexts) | OVERKILL | OVERKILL | OVERKILL | SELECTIVE | APPROPRIATE |
| Message queues | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE | REQUIRED |
| API versioning | SKIP | SKIP | URL prefix | Header-based | Full strategy |
| Error handling | try/catch | console.log | Error boundary | Error service | RFC 9457 |
| Logging | console.log | none | Structured JSON | Centralized | OpenTelemetry |

**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

| Choice | Interview | Hackathon | MVP | Growth | Enterprise |
|--------|-----------|-----------|-----|--------|------------|
| **Database** | SQLite / JSON file | In-memory / SQLite | Managed Postgres | Postgres + Redis | Postgres + queues + cache |
| **Auth** | Hardcoded / none | None | Clerk / Supabase Auth | Auth service | OAuth2 / SAML / SSO |
| **State mgmt** | useState | useState | Zustand / Context | Zustand + React Query | Redux / custom + cache |
| **CSS** | Inline / Tailwind | Tailwind | Tailwind | Tailwind + design tokens | Design system |
| **API** | Express routes | Single file handler | Next.js API routes | FastAPI / Express | Gateway + services |
| **Deployment** | localhost | Vercel / Railway | Vercel / Railway | Docker + managed | K8s / ECS |
| **CI/CD** | None | None | GitHub Actions basic | Multi-stage pipeline | Full pipeline + gates |
| **Monitoring** | None | None | Error tracking only | APM + logs | Full observability stack |

---

## Build vs Buy Decision Tree (Tiers 1-3)

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

| Capability | BUY (use SaaS) | BUILD (only if) |
|-----------|----------------|-----------------|
| Auth | Clerk, Supabase Auth, Auth0 | Core product IS auth |
| Payments | Stripe | Core product IS payments |
| Email | Resend, SendGrid | Core product IS email |
| File storage | S3, Cloudflare R2 | Compliance requires on-prem |
| Search | Algolia, Typesense Cloud | > 10M docs or custom ranking |
| Analytics | PostHog, Mixpanel | Unique data requirements |

**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>")`:
| File | Content |
|------|---------|
| `interview-takehome.md` | Tiers 1-2 in detail |
| `startup-mvp.md` | Tier 3 patterns and decisions |
| `enterprise.md` | Tiers 4-5 patterns and justification criteria |
| `open-source.md` | Tier 6 unique considerations |