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:

• brainstorming 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:brainstorming - 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

• Interview & Take-Home Guide - Tiers 1-2 in detail
• Startup & MVP Guide - Tier 3 patterns and decisions
• Enterprise Guide - Tiers 4-5 patterns and justification criteria
• Open Source Guide - Tier 6 unique considerations

References (4)

Enterprise

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 Takehome

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

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

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: