Sysdesign

Phase 1: Requirements

Ask the user about each area. Skip what's not relevant.

Functional Requirements

• What does the user/system do? (user stories or use cases)
• What data is created, read, updated, deleted?
• What external systems interact with this?

Non-Functional Requirements

• Expected scale: users, requests/sec, data volume
• Latency requirements: real-time? near-real-time? batch?
• Auth requirements: public, authenticated, role-based?
• Offline/degraded mode needs?

Constraints

• Vercel plan limits (serverless function timeout, bandwidth)
• Supabase plan limits (database size, realtime connections, storage)
• Must integrate with existing tables/APIs? Which ones?

System Boundary

Define what is inside and outside this design:

• In scope: What this system directly controls (tables, APIs, UI)
• Out of scope: What this system depends on but doesn't own (auth provider, external APIs, existing tables)
• Boundary crossings: What crosses the boundary? (API calls in/out, webhooks, shared database tables, file uploads)

Understanding the boundary is critical — most bugs live at the edges where systems meet.

Checkpoint: Present a requirements summary including the system boundary. Confirm before proceeding.

Phase 2: Systems Map

Map the dynamic behavior of the system before choosing components. This phase answers: how will this system behave over time?

Small feature heuristic: If this feature touches a single table and a single API endpoint with no background processing, compress the systems map to a single paragraph summarizing: what accumulates, what drives change, and whether there's any feedback.

Step 2a: Identify Stocks

Ask: "What accumulates in this system?"

Think about:

• Database rows that grow over time (invitations, messages, uploads, logs)
• Queue entries waiting to be processed
• Cached items that build up and expire
• Active sessions or connections
• User-visible counts (unread notifications, pending requests)

For each stock, note:

Step 2b: Identify Flows

Ask: "What causes each stock to increase or decrease?"

For each stock, identify:

• Inflows: What adds to it? (user actions, cron jobs, webhooks, API calls)
• Outflows: What drains it? (processing, expiry, deletion, archival)
• Rate: Is the flow steady, bursty, or user-driven?

Step 2c: Identify Feedback Loops

Ask: "Does any output of this system influence its own input?"

Look for:

• Reinforcing loops (snowball effects): Does success breed more success? Does a failure cause more failures?
  • "If users invite teammates, do those teammates invite more users?"
  • "If an API call fails and retries, could the retries cause more failures?"
• Balancing loops (self-correction): Does the system naturally resist change?
  • "Is there a rate limit, quota, or cap that pushes back against growth?"
  • "Does the system auto-heal? (cache refresh, retry with backoff, rebalancing)"

For each loop found:

Consult references/systems-thinking-catalog.md → Feedback Loop Taxonomy for common patterns.

Step 2d: Identify Delays

Ask: "Where does time lag exist between an action and its effect?"

Common delays in this stack:

• ISR revalidation: Content updates aren't visible until revalidation fires
• Eventual consistency: Supabase Realtime has delivery lag
• Cron intervals: Edge Function cron jobs run on a schedule, not instantly
• DNS/CDN propagation: Cache purge takes time to propagate
• Human delays: User might not respond to an invite for days

For each delay:

Systems Map Summary

Present the complete map: stocks, flows, loops, and delays in a brief narrative.

"This system has N stocks. The primary dynamic is [describe main behavior]. There are [reinforcing/balancing] loops around [X]. The key delays are [Y]. The biggest risk from a systems perspective is [Z]."

Checkpoint: Confirm the systems map before designing components.

Phase 3: Component Design

Design each relevant stack layer. Use the systems map to inform decisions — every component should trace back to a stock it manages, a flow it controls, or a feedback loop it participates in.

Reference references/stack-components.md for tactical decision tables and checklists for each layer.

For each component, answer:

1. What stock/flow does this component serve? (traceability to Phase 2)
2. What rendering/API/DB pattern fits? (consult stack-components.md)
3. How does this component handle the delays identified in Phase 2?
4. Does this component participate in any feedback loop? If so, is that loop properly bounded?

Layers to design (skip what's not relevant):

• Database schema — Tables, columns, types, relationships, indexes, RLS policies
• API layer — Server Actions, Route Handlers, Edge Functions, Middleware
• Frontend — Pages, components, rendering strategy, state management
• Auth — Method, role model, metadata storage
• Storage — Buckets, upload method, size limits
• Realtime — Which tables, channel type, authorization

For each layer, run through the relevant checklist in references/stack-components.md.

Checkpoint: Present the architecture. Confirm before integrity check.

Phase 4: Integrity Check

Scan the design for known system failure patterns, then assess where decisions fall on the leverage spectrum.

Step 4a: Archetype Scan

Ask these detection questions about the design. If any answer is "yes" or "maybe," flag it and propose a mitigation.

Quick fixes masking root causes:

• Does any part of this design apply a workaround rather than addressing root cause?
• Are there "temporary" solutions that might persist? (cron jobs clearing stale data, manual cache invalidation, retry loops masking flaky services)

Dangerous dependencies:

• Does this design make a third-party service load-bearing in a way that weakens a capability we should own?
• Is there a single point of failure that everything routes through?

Eroding standards:

• Are there quality thresholds that might slip under pressure? ("we'll add tests later," "this RLS policy is good enough for now")
• Does the design rely on discipline rather than automation to maintain standards?

Arms races:

• Is there anywhere two components might escalate against each other? (retries vs rate limits, cache invalidation vs cache rebuilding)
• Could defensive behavior in one component trigger defensive behavior in another?

Growth hitting walls:

• If this feature succeeds wildly, what breaks first? (connection pool, storage quota, Vercel bandwidth, Supabase plan limits)
• What's the upgrade path when the limit is reached?

Shared resource contention:

• Is there a shared resource that multiple users or features consume without coordination? (connection pool, API rate limits, storage quota)
• Could one heavy user degrade the experience for everyone else?

Consult references/systems-thinking-catalog.md → System Archetypes for deeper descriptions, software examples, and resolution strategies.

Step 4b: Leverage Assessment

For the key decisions in this design, note where each intervenes on the leverage spectrum:

Consult references/systems-thinking-catalog.md → 12 Leverage Points for the full ladder.

If most decisions are low-leverage (parameters, buffer sizes), ask: "Is there a higher-leverage intervention that would make several of these low-leverage tweaks unnecessary?"

Step 4c: Design Checklist

Run through references/stack-components.md → Design Checklist (performance, security, reliability, observability).

Checkpoint: Present findings from archetype scan and leverage assessment. Confirm mitigations before finalizing.

Phase 5: Trade-offs

For each decision point where multiple valid options exist:

### Decision: [What needs to be decided]

| Criterion     | Option A        | Option B        |
|---------------|-----------------|-----------------|
| Complexity    | ...             | ...             |
| Performance   | ...             | ...             |
| Cost          | ...             | ...             |
| Maintenance   | ...             | ...             |
| Leverage level| [low/med/high]  | [low/med/high]  |
| Fits stack?   | ...             | ...             |

**Recommendation:** [Option] because [reasoning]
**Systems note:** [How this choice affects the feedback loops / delays / stocks identified in Phase 2]

Phase 6: Output — Design Document

Produce the final design doc in this format:

## Design: [Feature/System Name]

### Overview
[2-3 sentence description of what this system does]

### Requirements
- [Functional requirement 1]
- [Functional requirement 2]
- [Non-functional: scale, latency, auth]
- **System boundary:** [What's in scope, out of scope, and what crosses the boundary]

### Systems Map

**Stocks:**
| Stock | Location | Grows unbounded? |
|-------|----------|-----------------|
| ... | ... | ... |

**Key flows:**
| Stock | Inflow | Outflow |
|-------|--------|---------|
| ... | ... | ... |

**Feedback loops:**
| Loop | Type | Effect |
|------|------|--------|
| ... | ... | ... |

**Critical delays:**
| Delay | Duration | Risk |
|-------|----------|------|
| ... | ... | ... |

**Systems narrative:** [1-2 sentences on the dominant dynamic]

### Architecture
[Component diagram or description of how pieces connect, with traceability to systems map]

### Database Schema
[Tables, columns, types, relationships, RLS policies]

### API Design
[Endpoints/actions, request/response shapes]

### Frontend
[Pages, components, rendering strategy, state management]

### Integrity Check Results
- **Archetypes flagged:** [list any that apply, with mitigations]
- **Leverage assessment:** [summary — are we intervening at the right level?]
- **Design checklist:** [pass/fail with notes on any failures]

### Trade-offs
[Key decisions made and why, with leverage level and systems impact noted]

### Open Questions
- [ ] [Anything unresolved that needs input]

### Ready for /write-plan
[Yes/No — if yes, user can run /write-plan to break this into tasks]

Examples

Input: "Design a team invitation system for my app"

Systems map highlights:

• Stocks: pending invitations (grow with sends, drain with accept/decline/expiry)
• Reinforcing loop: invitations → new team members → more invitations (if members can also invite)
• Key delay: human response time (days between send and accept)
• Growth limit: email send rate limits, Supabase row limits

Architecture highlights:

• invitations table with status enum, expiry, token
• RLS: team admins can INSERT, invitee can UPDATE (accept/decline)
• Server Action for sending invite (creates record + sends email via Edge Function)
• ISR for public invite page, SSR for dashboard
• Cron Edge Function to expire old invitations (manages stock drain)

Integrity check:

• Escalation risk: none (no competing components)
• Growth limit: email provider rate limits if bulk invites enabled → mitigation: queue + batch send
• Drifting goals risk: expiry cron might get disabled "temporarily" → mitigation: monitoring alert if pending invitations stock grows beyond threshold

Input: "Design a file sharing feature with permissions"

Systems map highlights:

• Stocks: uploaded files (grow with uploads, drain with deletion), shared access grants
• Reinforcing loop: more shared files → more collaboration → more uploads
• Key delay: signed URL expiry (time-limited access window)
• Shared resource: storage bucket quota

Architecture highlights:

• Supabase Storage buckets per team (private)
• files metadata table with shared_with junction table
• Signed URL generation via Route Handler
• RLS: owner + shared users can SELECT, owner-only DELETE
• CSR file browser with SWR for listing, optimistic upload UI

Integrity check:

• Tragedy of the commons: one team consuming all storage → mitigation: per-team storage quotas
• Fixes that fail: if large files slow queries, don't just add caching — add pagination and lazy loading of file metadata
• Growth limit: Supabase Storage plan limits → clear upgrade path documented

Error Handling