📁 LLMRules.md

#🤖 LLM Rules — System Design Topic Generation

Purpose: This document defines the exact rules, structure, and checklist an LLM must follow when generating a new system design topic for this repository. Follow every section. Skip nothing.

#📌 Trigger

When a user provides a one-liner like "Design X" or "Design a Y system", the LLM must generate a complete, end-to-end system design document and update all cross-referenced files.

#📁 File & Folder Structure

system-design/
├── README.md                          ← Master index (UPDATE)
├── LLMRules.md                        ← You are here
├── notes/
│   ├── concept-map.md                 ← Central concept hub (UPDATE)
│   └── *.md                           ← Concept notes (CREATE if missing)
├── topics/
│   └── {NN}-{topic-slug}.md           ← Design document (CREATE)
└── building-blocks/
    ├── reference.md                   ← Building blocks index (UPDATE)
    └── *.md                           ← Building block files (CREATE if missing)

#Naming Conventions

#📝 Topic Document Template

Every topic document in topics/ MUST follow this exact 12-section structure. No sections may be skipped.

# Design [System Name] ([Scale Reference] Scale)

## 1. Problem Statement & Clarifications
### Functional Requirements     ← 4-6 numbered, bolded requirements
### Non-Functional Requirements ← Table format: Requirement | Target
### Out of Scope                ← 3-5 bullet points of what we're NOT designing
### Assumptions                 ← 3-5 bullet points

## 2. Back-of-Envelope Estimation
### Traffic Estimates            ← Code block with calculations
### Storage Estimates            ← Code block with calculations
### Bandwidth                    ← Code block with calculations
### Cache Estimates              ← Code block with calculations

## 3. API Design
### [Core API 1]                 ← Full request/response JSON examples
### [Core API 2]                 ← Include HTTP method, path, headers
### [Internal API if needed]     ← Mark internal APIs explicitly

## 4. Data Model
### [Store 1] ([Technology](link) — sharding/partitioning strategy)
### [Store 2]                    ← SQL CREATE TABLE or NoSQL schema
### Access Patterns              ← Table: Query | Store | Index/Key

## 5. High-Level Design (HLD) & Scale Evolution
### Stage 1: MVP / Startup Scale ← Simple architecture + bottlenecks
### Stage 2: Growth Scale        ← Key architectural changes + bottlenecks
### Stage 3: [Target] Scale      ← Full architecture
#### Architecture Diagram        ← ASCII art diagram
#### Component Breakdown         ← Table: Component | Responsibility | Tech Choice
#### Data Flow                   ← Write Path + Read Path (code block arrows)

## 6. Deep Dive — Core Components
### [Component 1] — Detailed Design
### [Component 2] — Detailed Design
### Scaling Strategy             ← Table: Component | Strategy
### Caching Strategy             ← ASCII art multi-layer diagram
### Consistency Models           ← Table: Data | Model | Rationale (LINK to notes)

## 7. Low-Level Design — Core Functionality
### Key Algorithms               ← 2-4 algorithms with pseudocode (Python preferred)
### Design Patterns Used         ← Table: Pattern | Where | Why (LINK to notes)

## 8. Failure Handling & Edge Cases
### What Happens When X Fails?   ← Table: Failure | Impact | Mitigation
### [Domain-Specific Edge Cases] ← Bullet points with → mitigation

## 9. Monitoring & Observability
### Key Metrics                  ← Table: Metric | Target | Alert Threshold
### Alerting Strategy            ← P0 / P1 / P2 tiers
### SLAs / SLOs                  ← Code block with targets

## 10. Trade-off Summary
← Table: Decision | Chose | Over | Because (6-10 rows)

## 11. Extensions & Follow-ups
### What Would You Add With More Time?  ← 4-6 numbered items
### How Would This Change at 100x Scale? ← 3-4 bullet points

## 12. Cross-References
### Related Topics in This Repo  ← Table: Topic | Connection
### Building Blocks Used         ← Bullet list with LINKS to building-blocks/
### Concepts Used                ← Bullet list with LINKS to notes/

#🔗 Deep Linking Protocol (MANDATORY)

This is the most critical rule. Every mention of a technology or concept MUST be hyperlinked to its corresponding file.

#Rules

  1. Technologies → Link to building-blocks/{tech}.md

    ✅ [Redis](../building-blocks/redis.md)
✅ [PostgreSQL](../building-blocks/postgresql.md) — [sharded](../notes/sharding.md)
✅ [Kafka](../building-blocks/kafka.md)

❌ Redis
❌ **Redis**
❌ Redis (no link)

  2. Concepts/Patterns → Link to notes/{concept}.md

    ✅ [CQRS](../notes/cqrs.md)
✅ [Consistency Models](../notes/consistency-models.md)
✅ [Event Sourcing](../notes/event-sourcing.md)

❌ CQRS pattern
❌ Event Sourcing (mentioned without link)

  3. First mention in each major section should be linked. Subsequent mentions in the same paragraph need not be.

  4. Section 4 (Data Model) headers must include technology links:

    ✅ ### Transaction Store ([Cassandra](../building-blocks/cassandra.md) — high write throughput)
✅ ### User Profiles ([PostgreSQL](../building-blocks/postgresql.md) — [sharded](../notes/sharding.md) by user_id)

  5. Section 12 (Cross-References) must link ALL building blocks and concepts used.

#🧱 Building Block File Rules

#When to Create

Create a new building-blocks/{tech}.md if the topic uses a technology that does not already have a file in the building-blocks/ directory.

#Check Existing First

Before creating, check for these existing files:

building-blocks/
├── cassandra.md        ├── kafka.md
├── cdn.md              ├── load-balancer.md
├── dynamodb.md         ├── postgresql.md
├── elasticsearch.md    ├── redis.md
├── flink.md            ├── s3.md
├── vector-db.md        └── reference.md

#Template

# 🧱 Building Block: [Full Technology Name]

## Overview
[1-2 sentence description of what it is]

## Key Concepts
- **[Concept 1]**: [Explanation]
- **[Concept 2]**: [Explanation]
- **[Concept 3]**: [Explanation]
(4-8 concepts)

## When to Use
- **[Use Case 1]**: [When and why]
- **[Use Case 2]**: [When and why]
(3-5 use cases)

## When NOT to Use   ← Optional but preferred
- [Anti-pattern 1]
- [Anti-pattern 2]

## Trade-offs
- **Pros**: [List strengths]
- **Cons**: [List weaknesses]

## Used In This Repo
- [Topic Name (#NN)](../topics/NN-slug.md) — [How it's used]
- [Topic Name (#NN)](../topics/NN-slug.md) — [How it's used]

#📝 Concept Note File Rules

#When to Create

Create a new notes/{concept}.md if the topic uses a design pattern or concept that does not already have a file in the notes/ directory.

#Check Existing First

notes/
├── bloom-filters.md       ├── cqrs.md
├── circuit-breaker.md     ├── event-sourcing.md
├── concept-map.md         ├── sharding.md
└── consistency-models.md

#Template

# 📝 Note: [Concept Name]

## Overview
[1-2 sentence definition]

## Core Idea
- **[Aspect 1]**: [Explanation]
- **[Aspect 2]**: [Explanation]

## [Comparison Table if applicable]
| Aspect | Option A | Option B |
(optional but encouraged)

## When to Use
- [Scenario 1]
- [Scenario 2]

## When NOT to Use
- [Anti-pattern 1]

## Trade-offs
- **Pros**: [List]
- **Cons**: [List]

## Used In This Repo
- [Topic Name (#NN)](../topics/NN-slug.md) — [How it's used]

#🗺️ Concept Map Update Rules

After creating a topic, you MUST update notes/concept-map.md:

  1. Add new rows for any new technology or concept introduced.
  2. Update existing rows by appending the new topic to the "Related Topics" column.
  3. Link to deep-dive files in the "Deep Dive / Notes" column. Use — if no deep-dive file exists.

#Format

| Concept | Related Topics | Deep Dive / Notes |
|---------|---------------|-------------------|
| **Redis** | [E-Commerce (#11)](../topics/11-ecommerce.md), [NEW TOPIC (#NN)](../topics/NN-slug.md) | [building-blocks/redis.md](../building-blocks/redis.md) |

#📚 Reference Index Update Rules

After creating a topic, you MUST update building-blocks/reference.md:

  1. Add new building blocks to the appropriate category table (Data Storage / Compute & Networking / Messaging & Streaming).
  2. Add new concept notes to the Cross-Cutting Concepts table.
  3. Update the "Used In" column of existing entries if the new topic uses them.

#📋 README Update Rules

After creating a topic, you MUST update README.md:

  1. Find the topic index table in the appropriate section (🟢 Fundamentals / 🟡 Product Systems / 🔴 Advanced / ⚫ Expert-Level).
  2. Add a new row:
    | NN | Design [System Name] | `topics/NN-slug.md` | ✅ Done |
  3. If the topic doesn't fit an existing section, add it to ⚫ Expert-Level.

#✅ Pre-Submission Checklist

Before considering the task complete, verify ALL of the following:

#Topic Document

#Deep Linking

#Supporting Files

#🎨 Style Guide

#Tone

#Formatting

#Scale References

#Pseudocode

#Numbers