scalable-thinking

Design for scale while keeping implementation simple (KISS).

⭐3stars🔀2forks📁View on GitHub🕐Updated Jan 8, 2026

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.
namescalable-thinking
description"Design for scale while keeping implementation simple (KISS)."
autoInvokefalse
priorityhigh

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

  1. Think Scalable: Data models that grow, APIs that evolve, architecture that supports change
  2. Build Simple: Simplest implementation first, standard patterns, no premature optimization
  3. 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