Machine Learning System Design

A practical collection of end-to-end ML system design documents, templates, and checklists — a companion to the book Machine Learning System Design (Manning).

This repository provides structure and a variety of design documents you can use as references and starting points for your own work. It doesn't aim to replace the full teaching experience of the book — instead, it gives you concrete, worked examples of what good ML system design documents look like in practice.

Repository Structure

├── templates/                       # Templates and guidelines
│   ├── basic_ml_design_doc.md       # Template for ML design docs
│   └── design_doc_checklist.md      # Review checklist for design docs
├── Design_Doc_Examples/             # Example design documents
│   ├── Examples/                    # Real-world–inspired examples
│   │   └── EN/                      # English examples
│   └── Mock/                        # Educational mock examples
│       └── EN/                      # English mock examples
├── skills/                          # Agent skills (ml-system-design-review)
├── BookOutline.md                   # Book chapter summaries and key concepts
├── CONTRIBUTING.md                  # Contribution guidelines
├── LICENSE                          # MIT License
└── README.md                        # This file

Getting Started

1. New to ML System Design?

   • Start with BookOutline.md for the key concepts, chapter by chapter.
   • Read a full worked example: Retail Demand Forecasting.
   • Use the design document template for your own designs.

2. Writing your own design doc?

   • Copy templates/basic_ml_design_doc.md and fill it in section by section.
   • Run through the review checklist before sharing it.
   • Compare against the examples for depth and tone.

3. Looking for examples?

   • Design_Doc_Examples/ contains worked examples across different domains and complexity levels.
   • Retail Demand Forecasting — a real-world–inspired forecasting system.
   • RAG Chat with Document Versions — an educational mock of a RAG system.

New: Agent Skill For Design Review

This repository now ships ml-system-design-review — an agent skill that applies the book's framework to review ML/AI system designs: a verdict, a stage-aware gradecard, severity-ranked findings, and a prioritized fix plan for a design doc, a repo, or both.

npx skills add ML-SystemDesign/MLSystemDesign

See skills/README.md for details and usage.

Templates

We provide two main artifacts:

1. basic_ml_design_doc.md — a section-by-section template for ML system design documents.
2. design_doc_checklist.md — a review checklist to sanity-check a design doc before sign-off.

How the Template Maps to the Book

Each section of the design document template corresponds to one or more chapters of the book:

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines. Key areas for contribution:

• New design document examples
• Template improvements
• Best-practices documentation
• Reviews and feedback

License

This repository is licensed under the MIT License — see the LICENSE file for details.

Acknowledgments

• Based on concepts from Machine Learning System Design.
• Contributors to the examples and templates.
• The ML community, for feedback and improvements.