scalable-thinking
Design for scale while keeping implementation simple (KISS).
When & Why to Use This Skill
The Scalable Thinking skill provides a strategic framework for designing software systems that balance long-term growth with immediate simplicity. By applying the KISS (Keep It Simple, Stupid) principle to complex architectural challenges, it helps developers build robust data models, versioned APIs, and maintainable code structures that can scale 10x without unnecessary overhead or premature optimization.
Use Cases
- Database Schema Design: Creating normalized and indexed database structures that ensure high performance and queryability as data volume grows.
- Scalable API Development: Implementing RESTful, versioned APIs with built-in pagination and structured error handling to support evolving client needs.
- Modular Code Organization: Structuring projects using feature-based hierarchies to maintain readability and facilitate collaboration in expanding codebases.
- Strategic Infrastructure Scaling: Utilizing a data-driven checklist to decide when to introduce complexity, such as transitioning from monoliths to microservices or adding caching layers.
- Architectural Review: Evaluating existing designs against scalability anti-patterns to prevent technical debt and ensure systems remain simple for junior developers to understand.
| name | scalable-thinking |
|---|---|
| description | "Design for scale while keeping implementation simple (KISS)." |
| autoInvoke | false |
| priority | high |
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