scalable-thinking git:20260410.d55a9eaA

Immutable. This exact content never changes and is served at /api/v1/blob/4ca4ef5930862e5c.

---
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

**Principle:** 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

### Data Models
Separate related data into proper tables (not JSON strings). Enables querying, indexing, partitioning.

### APIs
RESTful resource paths with versioning: `/api/v1/users/:userId/processes`. Cacheable, evolvable.

### Database
Normalized tables with foreign keys and indexes. Not JSON blobs that can't be filtered.

### File Structure
Feature-based: `src/features/{feature}/{hooks,components,api}/` + `src/shared/`.

---

## Scalable Patterns

- **Pagination:** Cursor-based `?limit=20&cursor=abc` with `{ nextCursor, hasMore }`
- **Centralized config:** Single config object with env-based values
- **Structured errors:** `AppError` with code + statusCode

---

## Anti-Patterns

| Anti-Pattern | Instead |
|--------------|---------|
| Build for hypothetical 1M users | Simple monolith first |
| Pre-optimize with Redis | In-memory cache, add Redis when measured |
| Abstract for 1 use case | Direct impl, abstract at 2-3 examples |
| Microservices from day 1 | Monolith, split when team/features grow |

---

## Checklist

**Before designing:** Can model support 10x? Can I query needed data? Natural partition keys? API versioned? Pagination for lists?

**During:** Standard patterns? Simplest solution? Junior dev understandable? No abstractions until 3+ examples?

---

## When to Scale Up

Add complexity when: DB queries > 2s, API p95 > 500ms, error rate > 1%, 10x growth in 3 months, team > 5. Until then: keep simple, measure everything.

---