tomevault-io 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 |
| 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:
brainstormPhase 0 (context discovery)implementStep 0 (context discovery)quality-gatesYAGNI 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 ideasork:implement- Uses tier detection in Step 0 to constrain architectureork:quality-gates- YAGNI gate references this skill's tier matrixork: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 |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.