┌────────────────────────────────────────────────────────────────────────────┐
│                    SYSTEM DESIGN INTERROGATION                             │
├────────────────────────────────────────────────────────────────────────────┤
│                                                                            │
│                        ┌─────────────┐                                     │
│                        │   FEATURE   │                                     │
│                        │   REQUEST   │                                     │
│                        └──────┬──────┘                                     │
│                               │                                            │
│    ┌──────────────────────────┼──────────────────────────┐                │
│    │                          │                          │                │
│    ▼                          ▼                          ▼                │
│  ┌────────┐             ┌────────┐              ┌────────┐               │
│  │ SCALE  │             │  DATA  │              │SECURITY│               │
│  └───┬────┘             └───┬────┘              └───┬────┘               │
│      │                      │                       │                     │
│  • Users?               • Where?               • Who access?              │
│  • Volume?              • Pattern?             • Isolation?               │
│  • Growth?              • Search?              • Attacks?                 │
│      │                      │                       │                     │
│      └──────────────────────┼───────────────────────┘                     │
│                             │                                             │
│    ┌────────────────────────┼────────────────────────┐                   │
│    │                        │                        │                   │
│    ▼                        ▼                        ▼                   │
│  ┌────────┐           ┌──────────┐            ┌────────┐                │
│  │   UX   │           │COHERENCE │            │ TRADE- │                │
│  └───┬────┘           └────┬─────┘            │  OFFS  │                │
│      │                     │                  └───┬────┘                │
│  • Latency?           • Contracts?           • Speed?                    │
│  • Feedback?          • Types?               • Quality?                  │
│  • Errors?            • API?                 • Cost?                     │
│      │                     │                      │                      │
│      └─────────────────────┴──────────────────────┘                      │
│                             │                                             │
│                             ▼                                             │
│                     ┌───────────────┐                                    │
│                     │ IMPLEMENTATION│                                    │
│                     │    READY      │                                    │
│                     └───────────────┘                                    │
│                                                                            │
└────────────────────────────────────────────────────────────────────────────┘

Feature: "Add document tagging"
- Users: 1000 active users
- Documents per user: ~50 average
- Tags per document: 3-5
- Total tags: 50,000 → 500,000
- Access: Read-heavy (10:1 read:write)
- Search: Need tag autocomplete (prefix search)

Feature: "Add document tagging"
- Data: Tags belong WITH documents (denormalized) or separate table?
- Pattern: Get tags for document (by doc_id), get documents by tag
- Storage: PostgreSQL (relational) or add to document JSON?
- Search: Full-text for tag names, filter by tag for documents
- Decision: Separate `tags` table with many-to-many join

Feature: "Add document tagging"
- Access: User can only see/manage their own tags
- Isolation: All tag queries MUST include tenant_id filter
- AuthZ: Check user owns document before tagging
- Attacks: Tag injection? Limit tag length, sanitize input
- PII: Tags might contain PII → treat as sensitive

Feature: "Add document tagging"
- Latency: < 100ms for add/remove tag
- Feedback: Optimistic update, show tag immediately
- Failure: Rollback tag, show error toast
- Optimistic: Yes - add tag to UI before server confirms
- Workflow: Tags should be inline editable, no modal

Feature: "Add document tagging"
- Layers: DB → Backend API → Frontend UI → State
- Contracts: Document type needs `tags: Tag[]` field
- Types: Tag = { id: UUID, name: string, color?: string }
- Breaking: No - additive change to Document response
- API: POST /documents/{id}/tags, DELETE /documents/{id}/tags/{tag_id}

## Feature: [Name]

### Scale
- Users:
- Data volume:
- Access pattern:
- Growth projection:

### Data
- Storage location:
- Schema changes:
- Search requirements:
- Retention:

### Security
- Authorization:
- Tenant isolation:
- Attack surface:
- PII handling:

### UX
- Target latency:
- Feedback mechanism:
- Error handling:
- Optimistic updates:

### Coherence
- Affected layers:
- Type changes:
- API changes:
- Breaking changes:

### Decision
[Final approach with rationale]

/brainstorm → System Design Questions → Implementation Plan

❌ "I'll add an index later if it's slow"
   → Ask: What's the expected query pattern NOW?

❌ "We can add tenant filtering in a future PR"
   → Ask: How is isolation enforced from DAY ONE?

❌ "The frontend can handle any response shape"
   → Ask: What's the TypeScript type for this?

❌ "Users won't do that"
   → Ask: What's the attack vector? What if they DO?

❌ "It's just a small feature"
   → Ask: How does this grow with 100x users?