Add architecture diagrams to Bushel documentation

[leogdion]

Overview

Create visual diagrams to help developers understand Bushel's architecture and data flow.

Diagrams Needed

1. Data Flow Diagram

Show the complete sync process:

External APIs → Fetchers → Pipeline → Deduplication → CloudKit Records → Batch Upload

2. CloudKit Schema Relationships

Visualize record types and their references:

SwiftVersion ← XcodeVersion
     ↑              ↑
     |              |
     └── RestoreImage

3. Component Architecture

Show how modules interact:

Commands (CLI) → SyncEngine → BushelCloudKitService → MistKit → CloudKit API
                      ↓
              DataSourcePipeline → Fetchers

4. MistKit Integration Pattern

Diagram showing:

• ServerToServerAuthManager setup
• CloudKitService initialization
• Record operations flow
• Batch processing pipeline

Format Options

• Mermaid diagrams (renderable in GitHub README)
• ASCII art (simple, no external tools needed)
• Draw.io/Excalidraw files (professional look)
• SVG files (high quality, scalable)

Benefits

• Helps visual learners understand the codebase
• Useful for blog post illustrations
• Makes onboarding easier for new developers
• Serves as reference for Celestra implementation

Example (Mermaid)

graph TD
    A[External APIs] --> B[Fetchers]
    B --> C[DataSourcePipeline]
    C --> D[Deduplication]
    D --> E[RecordBuilder]
    E --> F[BushelCloudKitService]
    F --> G[MistKit]
    G --> H[CloudKit API]

Loading

Placement

• Add to README.md
• Consider separate ARCHITECTURE.md
• Include in blog post draft