{ "markdown": "

\n \"sysdesign\"\n

\n\n

\n \"release\"\n \"validate\"\n \"license\"\n \"Claude\n \"1\n \"15\n \"18\n \"self-contained,\n \"website\"\n

\n\n# sysdesign\n\n**English** · [العربية](README.ar.md) · [Español](README.es.md)\n\n**System design knowledge, wired into your AI agent.** A [Claude Code](https://claude.com/claude-code) plugin: one skill, fifteen commands, and eighteen self-contained reference files. Explain a concept, compare options, pressure-test an architecture, estimate capacity, or prep an interview — with tradeoffs stated, not hand-waved.\n\nThe knowledge lives in the files. There are **no external links inside the skill** — the agent loads the one reference a task needs, and the answer is right there. Original prose, inspired by the taxonomy of [ByteByteGo's *System Design 101*](https://github.com/ByteByteGoHq/system-design-101), never copied from it.\n\n```text\n$ /sysdesign:compare REST vs GraphQL vs gRPC\nconstraint? public API · mixed clients · cacheable\n REST HTTP caching, broad support ✓ default\n GraphQL one round trip, client picks fields cost: caching, N+1\n gRPC low-latency service-to-service cost: not browser-native\n› recommend REST. move off it only when a concrete pain justifies the cost.\n```\n\n---\n\n## Install\n\nIn **Claude Code**, run these two prompts:\n\n```\n/plugin marketplace add mkabumattar/sysdesign\n```\n\n```\n/plugin install sysdesign@sysdesign\n```\n\nThen `/reload-plugins` to apply. Try it:\n\n```\n/sysdesign:help\n/sysdesign:explain consistent hashing\n/sysdesign:compare REST vs GraphQL vs gRPC\n/sysdesign:review my checkout: gateway -> monolith -> single Postgres\n/sysdesign:estimate a URL shortener at 100M new links/day\n/sysdesign:interview design a news feed\n```\n\nUsing a different agent? **[INSTALL.md](INSTALL.md)** covers all ten harnesses with install,\nverify, update, and uninstall for each: Claude Code, Codex, Kimi Code CLI, Gemini CLI, GitHub\nCopilot, Zed, Hermes, Pi, Cursor/OpenCode/Amp, and Antigravity, plus a manual route for anything\nelse. The\nsame [install page](https://sysdesign.mkabumattar.com/install/) is on the site with a picker.\n\nEvery route loads the **same** `skills/system-design/` directory. The harness manifests point at\nit rather than shipping a copy, so no route can drift from another.\n\nOr just talk — the `system-design` skill activates on architecture/design questions without a command.\n\n## Update\n\nWhen a new version ships:\n\n```\n/plugin update sysdesign\n```\n\n```\n/reload-plugins\n```\n\nSee the [CHANGELOG](CHANGELOG.md) for what changed in each release.\n\n## The method\n\nEvery answer follows the same three moves:\n\n1. **State the constraint** — traffic pattern, consistency need, latency budget, team reality. No numbers? Assume out loud.\n2. **Pick the option that fits** — reuse before build, managed before self-hosted, boring before novel.\n3. **Name what you gave up** — every choice costs something: consistency, ops burden, latency, money.\n\nValidation at trust boundaries, data-loss handling, auth, and observability are never dropped to \"keep it simple.\"\n\n## What `/plan` does\n\nThe flagship command doesn't guess. It runs a short interview first, one system area per round, then writes a complete plan into a `.sysdesign-/` folder in your repo.\n\n

\n \"A\n

\n\n```text\n$ /sysdesign:plan a car marketplace\n▸ round 1/9 product & scope dealers + private sellers? on-platform payments?\n▸ round 2/9 users & scale ~2M listings, 10M MAU, read-heavy\n▸ round 3/9 data & consistency strong on reservations, eventual on search\n … auth · payments · media & search · infra · reliability …\n! conflict: 99.95% everywhere vs a team of 8. which wins?\n✓ requirements locked → writing .sysdesign-carbazaar/PLAN.md + requirements.md\n✓ validation round: confirm the design, resolve anything residual\n```\n\nIt never invents a requirement, pushes back when your answers conflict, and closes by validating the finished design. For an existing system reach for `/sysdesign:evolve`; to look something up, `/sysdesign:find`.\n\n## Commands\n\nFourteen thin wrappers over the one `system-design` skill, so the reasoning stays consistent.\n\n| Command | What it does |\n| --- | --- |\n| `/sysdesign:plan ` | Design end to end — a full multi-round interview, then a complete plan |\n| `/sysdesign:evolve ` | Evolve/migrate an existing system with a rollback-safe path |\n| `/sysdesign:explain ` | Explain a concept with tradeoffs and when to use it |\n| `/sysdesign:find ` | Search the references and surface the covering sections |\n| `/sysdesign:compare vs ` | Compare options, recommend one for your constraint |\n| `/sysdesign:review ` | Pressure-test a design for SPOFs and missing safeguards |\n| `/sysdesign:spec ` | Write the requirements and design document: brief, FDD/TDD, flows, schema, traceability |\n| `/sysdesign:audit ` | Audit a real codebase or infrastructure against the standards, ranked findings |\n| `/sysdesign:choose ` | Pick a DB / queue / cache / deploy strategy under constraints |\n| `/sysdesign:estimate ` | Back-of-envelope capacity: QPS, storage, bandwidth, memory |\n| `/sysdesign:tradeoffs ` | Name what a design choice gains and gives up |\n| `/sysdesign:diagram ` | Draw the architecture or a user flow as a draw.io `.drawio` file |\n| `/sysdesign:interview ` | Run interview prep with the 7-step framework |\n| `/sysdesign:cheatsheet ` | Condense an area into a scannable cheatsheet |\n| `/sysdesign:help` | List commands and reference topics |\n\n## Reference topics\n\nSeventeen standalone files under `skills/system-design/references/` — dense, tradeoff-first, no external links:\n\n`api-web` · `data-storage` · `caching-performance` · `distributed-systems` · `security-auth` · `devops-k8s` · `observability` · `cost-engineering` · `architecture-patterns` · `low-level-design` · `case-studies` · `networking` · `os-concurrency` · `payments` · `ai-ml-systems` · `dev-tools` · `design-docs` · `interview`\n\nTogether they cover every category of *System Design 101* — API & web, databases & storage, caching & performance, cloud & distributed systems, security, DevOps/CI-CD, software architecture, real-world case studies, technical interviews, computer fundamentals (networking + OS), payments & fintech, AI/ML, and dev tools — plus three domains it doesn't have: **observability** (SLOs, alerting), **cost engineering** (cloud unit economics), and **low-level design** (OOP, SOLID, machine-coding problems).\n\n## Why it's different\n\n- **Self-contained.** Zero external links inside `skills/`. A reader never has to click out.\n- **Tradeoff-first.** No option is named without the constraint it fits and the cost it carries.\n- **License-clean.** Original prose. MIT. Never reproduces *System Design 101*'s text or images.\n- **Works offline.** Plain Markdown and two JSON manifests. No build, no runtime, no telemetry.\n\n## Artifacts & export\n\nBeyond the skill, the repo ships shareable, **generic** outputs (nothing project- or vendor-specific):\n\n- `artifacts/diagrams/*.mmd` — original Mermaid sources (OAuth flow, sharding, caching layers, deploy strategies, request lifecycle, payments).\n- `scripts/export.py` — a self-contained [uv](https://docs.astral.sh/uv/) script that bundles the reference files into a numbered Markdown / PDF / docx set:\n\n```bash\nuv run scripts/export.py # → dist/ (git-ignored)\n```\n\n## Layout\n\n```\nsysdesign/\n .claude-plugin/ marketplace.json · plugin.json (icon wired)\n skills/system-design/ SKILL.md (router) + references/*.md (the knowledge)\n commands/ one .md per /sysdesign:\n evals/ paired quality harness: cases · rubric · release gate\n scripts/ validate.sh (CI checks) · export.py · run_evals.py\n artifacts/ generic Mermaid diagrams + index\n assets/ logo, icon, favicons, per-command glyphs\n site/ Astro landing page for sysdesign.mkabumattar.com\n .github/ CoC · contributing · security · issue templates · CI\n```\n\n## Develop\n\nNo compiler — validation is one script (the source of truth CI runs):\n\n```bash\nbash scripts/validate.sh\n```\n\nIt checks: manifests parse and versions match, zero external links in `skills/`, every reference file is mapped in `SKILL.md`, and frontmatter is present. See [CONTRIBUTING](.github/CONTRIBUTING.md) and, for the editorial system, [DESIGN.md](DESIGN.md).\n\nQuality is measured, not asserted. `evals/` runs the same twelve system-design cases with and\nwithout the skill and scores both blind against [the rubric](evals/rubric.md). The release gate\nrefuses a candidate unless it beats baseline on **tradeoff** (does the answer name what the\nchoice costs) and **clarify** (does it ask instead of assume) — the two things this skill exists\nto move. See [evals/README.md](evals/README.md).\n\nWhat's next lives in the [ROADMAP](ROADMAP.md) — one 1–2 day increment at a time.\n\n## Maintainer\n\nBuilt by **[Mohammad Abu Mattar](https://mkabumattar.com)** — Cloud & DevOps Manager, ~8 years across full-stack, backend, and platform engineering. sysdesign distills that tradeoff-first habit into a reference an agent can read.\n\nMore: [mkabumattar.com](https://mkabumattar.com) · [GitHub](https://github.com/mkabumattar) · [QuenchWorks](https://quench-works.com) (free, 0-CVE hardened image & chart catalog)\n\n## License\n\n[MIT](LICENSE) for this repository's original content. Topic taxonomy inspired by ByteByteGo's *System Design 101* (CC BY-NC-ND 4.0) — no text or images from it are reproduced here.\n", "bytes": 10984, "sha": "bc0933290bcb14c6ec06295edf1f5af163bc41e4d8113e6abbdf3e967b93fb07", "repo_slug": "mkabumattar/sysdesign", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_mkabumattar_sysdesign_cd2ed677/readme" }