| name | scalable-thinking |
| description | Design for scale while keeping implementation simple (KISS). |
| autoInvoke | false |
| priority | high |
| triggers | architecture, API design, data modeling, database schema |
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