Skill: Scalable Thinking

Purpose: Design for scale while keeping implementation simple (KISS) Priority: HIGH Auto-invokes: Architecture, API design, data modeling, database schema

Core Philosophy

"Think Scalable, Build Simple"

Aspect Scalable Thinking (WHAT) KISS (HOW)

Data Model Normalized, indexed Simple queries

API Versioned, RESTful Standard CRUD

Code Structure Feature-based Flat hierarchy

Config Centralized Single file

Where to Apply

1. Data Models

❌ Non-Scalable:

interface User { id: string preferences: string // JSON string - can't query }

✅ Scalable (Simple Implementation):

interface User { id: string; name: string; email: string } interface UserPreference { userId: string; key: string; value: string }

// Simple queries, can index by key, can partition by userId

2. API Design

❌ Non-Scalable:

POST /api/process { everything... }

✅ Scalable (Simple):

POST /api/v1/users/:userId/processes GET /api/v1/processes/:processId

Benefits: Versionable, RESTful, cacheable, evolvable

3. Database Schema

❌ Non-Scalable:

CREATE TABLE orders ( id UUID PRIMARY KEY, items JSON -- Can't filter by item );

✅ Scalable (Simple):

CREATE TABLE orders ( id UUID PRIMARY KEY, user_id UUID REFERENCES users(id), INDEX idx_user_id (user_id) );

CREATE TABLE order_items ( order_id UUID REFERENCES orders(id), product_id UUID, INDEX idx_order_id (order_id) );

4. File Structure

❌ Non-Scalable:

src/utils.ts # 5000 lines src/components.tsx # All components

✅ Scalable:

src/features/auth/hooks/, components/, api/ src/features/posts/hooks/, components/, api/ src/shared/hooks/, components/, utils/

Scalable Patterns

Always Plan For Pagination

// ❌ Returns all records GET /api/users → [...50,000 users]

// ✅ Cursor-based GET /api/users?limit=20&cursor=abc123 → { data: [...], pagination: { nextCursor, hasMore } }

Centralized Configuration

const config = { api: { baseUrl: process.env.API_URL, timeout: 5000 }, features: { /* feature flags */ }, limits: { maxFileSize: 10 * 1024 * 1024 } }

Structured Error Handling

class AppError extends Error { constructor( message: string, public code: string, public statusCode: number = 500 ) { super(message) } }

throw new AppError('User not found', 'USER_NOT_FOUND', 404)

Anti-Patterns to Avoid

Anti-Pattern Instead Do

Build for hypothetical 1M users Simple monolith first, scale when data shows need

Pre-optimize with Redis In-memory cache first, add Redis when measured

Abstract for 1 use case Direct implementation, abstract at 2-3 examples

Microservices from day 1 Monolith, split when team/features grow

Checklist

Before Designing

• Can data model support 10x more records?

• Can I query the data I'll need?

• Are there natural partition keys (userId, orgId)?

• Is API versioned (/v1)?

• Does pagination exist for lists?

During Implementation

• Am I using standard patterns?

• Is this the simplest solution?

• Can a junior dev understand this?

• No abstractions until 3+ examples?

When to Scale Up

Add Complexity When:

• Database queries > 2s consistently

• API response > 500ms at p95

• Error rate > 1%

• User growth > 10x in 3 months

• Team size > 5 developers

Until Then: Keep it simple, measure everything

Summary

• Think Scalable: Data models that grow, APIs that evolve, architecture that supports change

• Build Simple: Simplest implementation first, standard patterns, no premature optimization

• Iterate: Add complexity based on data, refactor when patterns emerge

Remember: Scalable ≠ Complex. Scalable = Can grow. KISS = Simple to maintain.

Applied In: Phase 2 (Design), Phase 5 (Implementation) Version: 1.0.0 | Last Updated: 2025-11-28