Diagram-First Principle¶

Core Idea: Visual explanations before text. If you can't draw it, you don't fully understand it.

The Problem: Text Overload¶

Complex systems are hard to understand from text alone:

"The Gateway service receives requests from the frontend, authenticates them
via the Auth service, then routes to the appropriate chatbot service (3D, Text,
or Voice) based on the chatbot type specified in the request. Each chatbot
service queries the LLM Model service for responses, which uses embeddings
stored in Milvus to perform RAG...

After 3 paragraphs: Reader is lost.

Our Solution: Diagram First¶

The same information as a diagram:

graph LR
    FE[Frontend] --> GW[Gateway :8000]
    GW --> AUTH[Auth :8001]
    GW --> CHAT3D[3D Chat :8011]
    GW --> CHATTXT[Text Chat :8012]
    GW --> CHATVOICE[Voice Chat :8013]

    CHAT3D --> LLM[LLM Service :8016]
    CHATTXT --> LLM
    CHATVOICE --> LLM

    LLM --> MILVUS[(Milvus)]

    style GW fill:#4CAF50
    style LLM fill:#2196F3
    style MILVUS fill:#FF9800

** Understood in 10 seconds.**

When to Use Diagrams¶

Always Diagram¶

When Text is Better¶

• API endpoint details (use tables)
• Configuration options (use lists)
• Error messages (use examples)
• Code snippets

Diagram Types We Use¶

1. System Architecture Diagrams¶

Purpose: Show component relationships

graph TB
    subgraph "Frontend"
        NEXTJS[Next.js App]
    end

    subgraph "Backend Services"
        GW[Gateway]
        AUTH[Auth]
        USER[User]
        CHAT[Chatbot Services]
    end

    subgraph "Data Layer"
        MONGO[(MongoDB)]
        MILVUS[(Milvus)]
        BLOB[Azure Blob]
    end

    NEXTJS --> GW
    GW --> AUTH
    GW --> USER
    GW --> CHAT

    AUTH --> MONGO
    USER --> MONGO
    CHAT --> MILVUS
    CHAT --> MONGO
    CHAT --> BLOB

Use Cases:

• Executive overviews
• Technical RFCs
• Architecture decision records
• Onboarding new team members

2. Sequence Diagrams¶

Purpose: Show process flows over time

sequenceDiagram
    participant User
    participant Frontend
    participant Gateway
    participant Auth
    participant ChatService
    participant LLM

    User->>Frontend: Type message
    Frontend->>Gateway: POST /api/chat
    Gateway->>Auth: Verify token
    Auth-->>Gateway: Token valid
    Gateway->>ChatService: Process message
    ChatService->>LLM: Generate response
    LLM-->>ChatService: AI response
    ChatService-->>Gateway: Response
    Gateway-->>Frontend: Response
    Frontend-->>User: Display message

Use Cases:

• API workflows
• Authentication flows
• Payment processing
• Error handling scenarios

3. Data Flow Diagrams¶

Purpose: Show how data moves through the system

flowchart LR
    A[User Uploads PDF] --> B[Data Crawling Service]
    B --> C[Extract Text]
    C --> D[Chunk into Segments]
    D --> E[Generate Embeddings]
    E --> F[(Store in Milvus)]
    F --> G[Ready for RAG Queries]

    style A fill:#E3F2FD
    style F fill:#FFF3E0
    style G fill:#E8F5E9

Use Cases:

• Data ingestion pipelines
• RAG architecture
• ETL processes -Analytics flows

4. State Diagrams¶

Purpose: Show state transitions

stateDiagram-v2
    [*] --> Draft
    Draft --> UnderReview: Submit for review
    UnderReview --> Approved: Approve
    UnderReview --> Draft: Request changes
    Approved --> Published: Publish
    Published --> Deprecated: Deprecate
    Deprecated --> [*]

    Draft: ✏️ Draft
    UnderReview: 🔍 Under Review
    Approved: ✅ Approved
    Published: 📢 Published
    Deprecated: ⚠️ Deprecated

Use Cases:

• Document lifecycle
• Chatbot conversation states
• Order/subscription states
• Feature flag status

5. Entity-Relationship Diagrams¶

Purpose: Show database schema

erDiagram
    USER ||--o{ CHATBOT : creates
    USER ||--o{ CONVERSATION : has
    CHATBOT ||--o{ CONVERSATION : contains
    CHATBOT ||--o{ KNOWLEDGE_BASE : uses
    CONVERSATION ||--o{ MESSAGE : includes

    USER {
        string id PK
        string email
        string name
        datetime created_at
    }

    CHATBOT {
        string id PK
        string user_id FK
        string name
        string type
        json config
    }

    CONVERSATION {
        string id PK
        string chatbot_id FK
        string user_id FK
        datetime started_at
    }

    MESSAGE {
        string id PK
        string conversation_id FK
        string role
        string content
        datetime timestamp
    }

Use Cases:

• Database design documentation
• API data models
• Migration planning

Diagram Tools & Standards¶

Primary Tool: Mermaid¶

Why Mermaid:

• ✅ Text-based (version control friendly)
• ✅ Renders in MkDocs automatically
• ✅ No external tools needed
• ✅ Generates beautiful diagrams

Basic Syntax:

```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
```

**Documentation:** [Mermaid Docs](https://mermaid.js.org/)

---

### Secondary Tool: Draw.io

**When to Use Draw.io:**
- Complex architecture diagrams
- Detailed infrastructure maps
- Diagrams needing custom shapes/icons
- Diagrams requiring collaboration

**Process:**
1. Create diagram in Draw.io
2. Export as SVG (vector format)
3. Save source `.drawio` file to `/docs/assets/diagrams/source/`
4. Save exported SVG to `/docs/assets/diagrams/`
5. Embed in documentation

**Example:**
```markdown
![System Architecture](../assets/diagrams/system-architecture.svg)

*Source: [system-architecture.drawio](../assets/diagrams/source/system-architecture.drawio)*

Diagramming Standards¶

Color Coding¶

Use consistent colors across all diagrams:

Naming Conventions¶

• Services: ServiceName :port (e.g., Gateway :8000)
• Databases: (DatabaseName) with cylinder shape
• External: Prefix with cloud icon or label
• Users: Use person icon

Style Guide¶

graph LR
    A[Clear Labels]
    B[Consistent Spacing]
    C[Logical Flow: Left→Right or Top→Bottom]
    D[Color for Meaning, Not Decoration]
    E[Keep It Simple]

    A --> B
    B --> C
    C --> D
    D --> E

    style A fill:#4CAF50,color:#ffffff
    style E fill:#4CAF50,color:#ffffff

Diagram Workflow¶

Creating a New Diagram¶

flowchart LR
    A[Identify Need] --> B{Complex Enough?}
    B -->|Yes| C[Sketch on Paper]
    B -->|No| D[Use Text/Table]
    C --> E[Create in Mermaid/Draw.io]
    E --> F[Add to Documentation]
    F --> G[Peer Review]
    G --> H{Approved?}
    H -->|No| E
    H -->|Yes| I[Merge]

Updating Existing Diagrams¶

When architecture changes:

1. Find affected diagrams:

grep -r "OLD_SERVICE_NAME" docs/

1. Update source:

2. For Mermaid: Edit markdown directly

3. For Draw.io: Open .drawio file, edit, re-export

4. Verify rendering:

mkdocs serve

1. Update version number:

_Last Updated: 2025-12-26 (v1.2)_

1. Commit with context:

git commit -m "docs: update architecture diagrams for Milvus migration

- Updated system-overview.md diagram
- Updated data-flow.md diagram
- Added Milvus to dependency graph

Related: ADR-003"

Diagram Best Practices¶

✅ Do¶

Keep It Simple

graph LR
    A[User] --> B[API]
    B --> C[Database]

Not:

[User with detailed persona description and multiple attributes]
→ [API Gateway with 15 microservices listed]
→ [Database cluster with replication topology]

Use Meaningful Labels

graph LR
    Frontend[Next.js Frontend] --> Gateway[API Gateway :8000]

Not:

graph LR
    A --> B

Show the Right Level of Detail

For executives:

graph LR
    Users --> MachineAvatars --> AI[AI Provider]

For engineers:

graph TB
    subgraph "Frontend"
        NEXT[Next.js]
        auth[NextAuth.js]
    end

    subgraph "Backend"
        GW[Gateway]
        AUTH[Auth Service]
        CHAT[Chat Service]
    end

    NEXT --> GW
    auth --> AUTH
    GW --> CHAT

❌ Don't¶

Don't Overload One Diagram

Bad: 50 boxes, 100 arrows, impossible to read

Good: Split into multiple diagrams:

• High-level overview (10 components)
• Detailed service diagram (per service)
• Data flow diagram (separate)

Don't Use Cryptic Abbreviations

Bad: USRSVC, AUTHSVC, DBCLSTR

Good: User Service, Auth Service, Database Cluster

Don't Forget the Legend

When using custom notation:

graph LR
    A[Service] --> B[Database]
    A -.->|Optional| C[Cache]
    A ==>|High Traffic| D[CDN]

    L1[Solid: Required]
    L2[Dotted: Optional]
    L3[Thick: High Traffic]

    style L1 fill:#ffffff,stroke:#000
    style L2 fill:#ffffff,stroke:#000
    style L3 fill:#ffffff,stroke:#000

Where Diagrams Live¶

In Documentation¶

docs/
  assets/
    diagrams/
      system-architecture.svg
      data-flow.svg
      rag-pipeline.svg
    diagrams/source/
      system-architecture.drawio
      infrastructure.drawio

In Code Repos¶

machineagents-be/
  docs/
    architecture.md  (contains Mermaid diagrams)
    diagrams/
      deployment.svg

Standalone Diagrams Pack¶

docs/14-appendices/diagrams-pack/
  01-system-overview.svg
  02-microservices-architecture.svg
  03-data-architecture.svg
  04-ai-ml-pipeline.svg
  05-security-architecture.svg
  README.md  (index of all diagrams)

Purpose: Download all diagrams for presentations, proposals, offsites.

Testing Diagrams¶

Readability Test¶

Test with new team member:

"Can you explain this system to me using only this diagram?"

If they struggle → diagram needs improvement.

Print Test¶

Print on A4 paper.

• Can you read all labels?
• Are arrows clear?
• Does it make sense at this size?

If no → simplify or split into multiple diagrams.

Color-Blind Test¶

Use tools like Coblis to verify diagrams work for color-blind readers.

Don't rely solely on color:

• Use shapes (circle, rectangle, diamond)
• Use patterns (solid, dashed, dotted)
• Use labels

Real-World Examples¶

Example 1: RAG Architecture¶

flowchart TB
    A[User Query] --> B[Query Preprocessing]
    B --> C[Generate Embedding]
    C --> D[Vector Search in Milvus]
    D --> E[Top-K Results]
    E --> F[Rerank with BM25]
    F --> G[Context Assembly]
    G --> H[Prompt + Context]
    H --> I[LLM Generation]
    I --> J[Response to User]

    K[(Knowledge Base)] --> D

    style A fill:#E3F2FD
    style D fill:#FFF3E0
    style I fill:#F3E5F5
    style J fill:#E8F5E9

With text explanation:

Our RAG system combines semantic search (vector embeddings) with keyword search (BM25) to retrieve the most relevant context for user queries. The retrieved context is then combined with the user's question and sent to the LLM for response generation.

Diagram + text = comprehensive understanding.

Example 2: Payment Flow¶

sequenceDiagram
    participant U as User
    participant FE as Frontend
    participant GW as Gateway
    participant PS as Payment Service
    participant RP as Razorpay
    participant DB as Database

    U->>FE: Select plan & click "Subscribe"
    FE->>GW: POST /api/payment/create
    GW->>PS: Create order
    PS->>RP: Create Razorpay order
    RP-->>PS: Order ID & details
    PS->>DB: Save order (pending)
    PS-->>FE: Order details
    FE->>U: Show Razorpay checkout
    U->>RP: Complete payment
    RP->>PS: Webhook: payment.success
    PS->>DB: Update order (paid)
    PS->>DB: Update user subscription
    PS-->>RP: Acknowledgment
    RP-->>U: Payment confirmation

This diagram prevents:

• Implementation errors
• Missing webhook handlers
• Race conditions
• Data inconsistencies

Keeping Diagrams Up-to-Date¶

Triggers for Diagram Updates¶

• New service added
• Service removed/deprecated
• Architecture change (ADR)
• Integration added/removed
• Database schema change
• Deployment architecture change

Review Schedule¶

Automated Checks¶

Broken image check:

# Run weekly
mkdocs build --strict  # Fails on missing images

Diagram inventory:

# List all diagrams
find docs/ -name "*.svg" -o -name "*.drawio"

Success Metrics¶

Tools Summary¶

Recommendation: Mermaid first, Draw.io for complex cases.

Related Principles¶

• Layered Readability - Diagrams work at all layers
• Audit-Ready - Diagrams provide visual proof
• SSOT - Diagrams version-controlled in docs repo

Last Updated: 2025-12-26
Version: 1.0
Owner: Documentation Lead

"A picture is worth a thousand words. A good diagram is worth ten thousand."