Learn system design with the agent you already use.
A stateful, first-principles systems tutor for your AI coding agent. Delivers interactive HTML failure simulators, unpacks engineering jargon inline, commits atomic state in your repository file CURSOR.md, tracks progress live on localhost, and won't let you advance until you defend architectural trade-offs cold in chat.
No remote database lock-in. Your living cursor, interactive simulators, verified invariants, and local progress tracker run strictly out of your project repository.
Step through kernel socket buffers, LSM compactions, and Raft split-brains in your browser.
Read-only localhost workbench in real-time sync with Git, featuring lesson player and styled notes.
Every sign-off records a tractable commit (sds(learn): ...) with one-command rollback safety.
Friendly essay prose with dedicated callouts for acronyms (HOL, LSM, WAL, 2PC) before referencing.
How it works
Four phases turn your AI coding agent into a stateful systems tutor with unannounced defense gates that verify true mastery before advancing.
Repository Scaffolding
The scaffolding script installs the .system-design/ directory into your local repository. 100% local files; zero external cloud services or databases.
.system-design/manifest.json
Progress in Git
CURSOR.md records the active topic, verified prerequisites, hardware invariants, and previous analogies. When your AI context resets, progress is preserved.
.system-design/CURSOR.md
Live Interactive Lessons
New topics are delivered strictly inside standalone interactive HTML artifacts with live simulators crafted per topic. Follow-up trade-off discussions happen inline in chat without lecture duplication.
.system-design/lessons/*.html
The Sign-Off Gate
It won't let you move on until you can defend it. The interactive lesson explores mechanics but hides the tick-off scenario. Progress in CURSOR.md advances only after you defend real trade-offs in chat.
Unannounced Chat Defense
The four layers of CURSOR.md
File-backed state on disk outlasts ephemeral AI chat context windows.
1. activeFocus
Tracks topic ID, depth tier, and active mechanism group. Ensures the tutor stays on the active objective without hallucinating tangents.
topicId: topic.0.1.tcp-vs-udp • depthLevel: physical-mechanics
2. causalAnchors
Records physical latency numbers and network boundaries verified during lessons so subsequent prompts reason from concrete bounds.
"Cold TCP + TLS 1.3 (no 0-RTT): 3 round trips before first byte"
3. examplesTaken
Registry of system domains used (financial ledger, audio streaming) to maintain continuity without repeating outdated analogies.
['financial-ledger-wal', 'live-webrtc-audio']
4. deferredQueue
Tracks tangent questions for upcoming clusters without breaking current topic focus. Processed only when foundation phase closes.
['QUIC connection migration across cellular handoffs']
Install For Your Agent
Single 1-line setup: detects active coding agents and installs the verified skill ready to use in any chat.
# Step 1: Install skill globally and configure machine preferences (theme, HTML vs MD, notes opt-in):
curl -fsSL https://raw.githubusercontent.com/alph-a07/system-design-studio/main/install.sh | bash
# Step 2: Initialize a project learning instance with curated tracks or BYO syllabus:
~/.system-design-studio/bin/sds init
# Step 3: Update on-demand when notified via in-chat /sds-update alert (preserves all progress & notes):
curl -fsSL https://raw.githubusercontent.com/alph-a07/system-design-studio/main/update.sh | bash
# Clean Uninstall (safely removes skill only from agents; strictly preserves projects, progress & notes):
curl -fsSL https://raw.githubusercontent.com/alph-a07/system-design-studio/main/uninstall.sh | bash
The "Two Scripts, Then Pure Chat" Lifecycle
Global Setup
Run install.sh once. The onboarding wizard configures your visual theme, HTML vs. Markdown output mode, and auto-notes opt-in at ~/.system-design-studio/.
Initialize Project
Scaffold a project instance in default projects/<name> or any repo. Select a curated goal track or import BYO markdown:
- › Interview Sprint (15 clusters / 114 topics)
- › Distributed Systems (23 clusters / 171 topics)
- › Staff+ System Defense (25 clusters / 184 topics)
- › Full 50-Cluster Mastery (354 topics)
Pure Chat Commands
Never touch a terminal again. Interact exclusively through chat commands across Antigravity, Claude Code, Cursor, and Codex:
- ›
/sds-teach [topic](deliver) - ›
/sds-discuss(defend cold) - ›
/sds-complete(sign off) - ›
/sds-projects(switch/list) - ›
/sds-delete <id>(safe delete)
Synthesized Notes
Topic sign-offs automatically compile comprehensive study notes combining physical invariants, your cold chat defense, edge cases, and trade-off formulas:
~/.system-design-studio/projects/<name>) or in any dedicated workspace or Git repository on your machine. All projects and their notes are tracked in the central multi-project registry.
Command Your Agent in Chat
Zero terminal commands during learning. Talk naturally to Claude Code, Cursor, Codex, or Antigravity—or use structured slash commands. The agent handles engine scripts silently under the hood.
Natural Language Fluency: You don't have to memorize slash syntax! Say "Teach me topic 0.1" or "Launch progress tracker on localhost" and your agent will execute the exact same state transitions.
Core Pedagogy & Defense
Controls the causal teaching loop, interactive simulators, Socratic stress-testing, and defense-gated advancement.
/sds-teach [topic]
Deliver Simulator
Renders interactive HTML simulator or Markdown diagram artifact with mandatory jargon unpacking. Prompts for your initial intuition or working hypothesis before exposing physical mechanics.
/sds-discuss
Socratic Dialectic
Stress-tests your hypothesis. For seniors, probes cold failure modes and latency bounds. For juniors, provides Socratic scaffolding questions without spoiling the unannounced gate.
/sds-complete [evidence]
Sign-Off & Git Commit
Verifies cold trade-off defense against hidden gate in CURRICULUM.md. Ticks topic, logs ADR in DECISIONS.md, advances CURSOR.md, compiles study notes (if auto-notes enabled), and commits atomic state to Git.
/sds-status
Progress & State
Inspects active topic, verified prerequisites, completion percentage, cognitive anchors, and deferred questions directly from disk.
Visual Workbench & Safety
Localhost visual progress tracker, atomic Git rollback, project-scoped notes, and multi-workspace management.
/sds-dashboard
Localhost Workbench
Launches read-only curriculum tracker on http://localhost:8420 in real-time sync with Git. Browse 50-cluster roadmap, test interactive HTML simulators, and read styled Markdown notes.
/sds-rollback
Reversible Undo
100% reversible safety net. Undo accidental topic completions or curriculum changes with atomic Git revert and local snapshot restoration (sds rollback --steps N).
/sds-notes [topic]
Study Notes
Lists active-learning study notes with clickable file:/// links. Auto-compiled on topic completion when enabled, or compiled on-demand when auto-notes is disabled.
/sds-projects
/sds-open <id>
/sds-delete <id>
Multi-project instances on one machine. /sds-projects lists all registered instances and track progress. /sds-open <id> switches active context. /sds-delete <id> safely deletes a project instance without touching code.
/sds-curriculum
/sds-config
/sds-update
/sds-curriculum mutates syllabus scoped to your project without losing completed progress. /sds-config sets visual themes, output formats, or auto-notes. /sds-update checks for new releases on-demand.
Five visual styles • Dual Output
Delivered strictly inside standalone interactive HTML simulators across 5 selectable themes, or zero-JS clean Markdown with Mermaid sequence & ASCII state charts.
Modern Slate
Deep slate-900 canvas with vibrant blue & indigo accents. Modern developer IDE feel.
slate-clean
#0f172a
Clean Editorial
Warm off-white paper canvas with sharp charcoal typography and crisp ink accents.
editorial-paper
#fbfbfa
Cyber Obsidian
Pitch black obsidian canvas with electric cyan and mint neon highlights. Futuristic HUD.
midnight-neon
#05070c
Nordic Frost
Subdued arctic cool night palette with frosty teal and snow-storm text. Zero eye strain.
nordic-frost
#2e3440
Warm Amber
Deep espresso stone with rich amber and copper embers designed for nighttime study.
warm-amber
#1c1917
Zero Redundant Chat Lectures • Interactive-First Learning
When entering a new topic, the entire lesson, physical constraints, packet simulator, and reality check are bundled exclusively into the HTML artifact. The chat stays clean with a direct link and discussion hook. All subsequent follow-ups, Q&A, and code traces happen inline directly in chat.
paths.cursorDir & paths.lessonsDir in settings.json to save cursor state and lessons wherever your repo requires.
Five tiers of systems engineering
From network transport and object modeling to distributed systems and mobile client sync across 354 topics.
HLD Building Blocks
APIs and transport foundations, database fundamentals, caching patterns, queues and quantitative estimation.
Low-Level Design & Modeling
Entity invariants, LRU/LFU cache evictions, connection poolers, rate limiting algorithms and thread executors.
HLD & Distributed Infra
Consistent hashing, write amplification (B-Tree vs LSM), consensus quorums, event sourcing, CDC and partition rebalancing.
Mobile Systems & Offline Sync
Battery limits, offline mutation queues, optimistic UI reconciliation, SQLite caching, push notification delivery and telemetry.
ADRs, Reviews & Spaced Gaps
Architecture Decision Records (ADRs), production trade-off defense, mock design reviews and spaced review loops.
Explore 50 Clusters
Browse the complete hierarchical syllabus grid, learning paths, and prerequisite graphs.
Engineered for Teams & Portfolios
Bring your company's internal tech stack or graduate with an interview-ready proof-of-work portfolio.
Bring Your Own Curriculum
Onboarding new engineers to a complex proprietary stack? Replace or extend CURRICULUM.md with your team's internal services, event brokers, storage layers, and architectural standards.
The AI tutor guides new hires through your company's exact topology topic by topic, verifying architectural principles with the same defense gates before they push to production.
Your Built-In ADR Portfolio
Every time you defend a design trade-off at the sign-off gate, the studio logs your architectural reasoning into DECISIONS.md as formal Architectural Decision Records.
Instead of abstract claims on your resume, you graduate with a Git-committed proof-of-work portfolio demonstrating deep trade-off evaluation under real latency, cost, and consistency constraints.
Comparison
How persistent file-based tutoring compares to a plain conversational chat.
| Dimension | A Plain AI Chat | System Design Studio |
|---|---|---|
| Advancement Gate | Nod-along agreement with no verification; advances whenever asked. | The Sign-Off Gate: Lesson hides tick-off scenario; won't advance until you defend trade-offs in chat. |
| State Across Sessions | Kept in conversational context window; lost when thread resets or model changes. |
Saved to CURSOR.md in Git; preserved across sessions and model switches.
|
| Teaching Approach | Text summaries and definitions generated per prompt. | Step-by-step topic curriculum anchored in hardware latency numbers. |
| Delivery Artifacts | Markdown codeblocks and text replies in chat. |
Standalone interactive HTML files with state and packet simulators in .system-design/lessons/.
|
| Decision Records | Ephemeral reasoning lost when context window rolls over. |
Logs your defenses into DECISIONS.md as an interview-ready ADR portfolio.
|
| Example Tracking | No record of previous analogies or examples across sessions. |
Logged in examplesTaken within CURSOR.md to avoid repeating scenarios.
|
| Curriculum Scope & Teams | Ad-hoc question answering with no shared curriculum across team members. |
Indexed 50 clusters in CURRICULUM.md; supports custom company stacks for onboarding.
|
Initialize your studio in 30 seconds.
Zero dependencies besides Git and Bash. Free and open source under MIT.
Support the Project
If System Design Studio untangled a tricky concept or made your prep a little easier, consider buying me a coffee ☕ or sponsoring my work.
⭐ Not in a coffee mood? No worries! A free Star on GitHub costs nothing but makes my day.
Happy designing, and thanks for being here!