Guides systems design and architecture for Supabase + Vercel + Next.js stack using Meadows' systems thinking framework. Maps system dynamics (stocks, flows, feedback loops, delays) before designing components, then scans for known failure patterns. Outputs a design doc compatible with /write-plan.
Structured systems design process grounded in Donella Meadows' "Thinking in Systems" framework, tuned to Ben's stack. You map the system dynamics first, then design components informed by that map, then scan for known failure patterns. Produces a design document that feeds directly into /write-plan.
/brainstorm, before /write-plan| Phase | Name | Purpose | Checkpoint |
|---|---|---|---|
| 1 | Requirements |
| Scope the system and draw its boundary |
| Confirm requirements |
| 2 | Systems Map | Map stocks, flows, feedback loops, and delays | Confirm systems map |
| 3 | Component Design | Design each stack layer informed by the systems map | Confirm architecture |
| 4 | Integrity Check | Scan for system archetypes and assess leverage points | Confirm mitigations |
| 5 | Trade-offs | Compare options with leverage level noted | — |
| 6 | Output | Produce design document for /write-plan | — |
Ask the user about each area. Skip what's not relevant.
Define what is inside and outside this design:
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.
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.
Ask: "What accumulates in this system?"
Think about:
For each stock, note:
| Stock | Where it lives | Units | Can it grow unbounded? |
|---|---|---|---|
| e.g., pending invitations | invitations table | rows | Yes — need expiry |
Ask: "What causes each stock to increase or decrease?"
For each stock, identify:
| Stock | Inflow | Outflow | Rate pattern |
|---|---|---|---|
| pending invitations | admin sends invite | user accepts/declines, expiry cron | bursty (batch invites) |
Ask: "Does any output of this system influence its own input?"
Look for:
For each loop found:
| Loop | Type | Components involved | Effect |
|---|---|---|---|
| invite virality | reinforcing | invitations → new users → more invitations | user growth accelerates |
Consult
references/systems-thinking-catalog.md→ Feedback Loop Taxonomy for common patterns.
Ask: "Where does time lag exist between an action and its effect?"
Common delays in this stack:
For each delay:
| Delay | Between what and what | Typical duration | Risk if ignored |
|---|---|---|---|
| ISR revalidation | data change → page update | 60s (configurable) | user sees stale data |
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.
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.mdfor tactical decision tables and checklists for each layer.
For each layer, run through the relevant checklist in references/stack-components.md.
Checkpoint: Present the architecture. Confirm before integrity check.
Scan the design for known system failure patterns, then assess where decisions fall on the leverage spectrum.
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:
Dangerous dependencies:
Eroding standards:
Arms races:
Growth hitting walls:
Shared resource contention:
Consult
references/systems-thinking-catalog.md→ System Archetypes for deeper descriptions, software examples, and resolution strategies.
For the key decisions in this design, note where each intervenes on the leverage spectrum:
| Decision | Leverage level | Why |
|---|---|---|
| Setting cache TTL to 60s | Low (parameter) | Tuning a number |
| Adding RLS policy for data ownership | High (rules) | Structural constraint that prevents a class of bugs |
| Switching to event-driven architecture | Very high (paradigm) | Changes how the system organizes itself |
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?"
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.
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]
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]
Input: "Design a team invitation system for my app"
Systems map highlights:
Architecture highlights:
invitations table with status enum, expiry, tokenIntegrity check:
Input: "Design a file sharing feature with permissions"
Systems map highlights:
Architecture highlights:
files metadata table with shared_with junction tableIntegrity check:
| Issue | Resolution |
|---|---|
| Requirements too vague | Return to Phase 1, ask specific questions |
| Feature spans multiple bounded contexts | Split into separate design docs, one per context |
| User unsure about scale | Design for current needs, note scaling decision points as growth limits in systems map |
| Systems map feels like overkill | Use the small feature heuristic — compress to one paragraph |
| Conflicts with existing schema | Use Supabase MCP to read current schema before designing |
| No feedback loops found | That's fine — simple systems exist. Note the absence and move on |
| Too many archetypes flagged | Prioritize by leverage level — fix highest-leverage issues first |