Microservices Communication

This diagram shows how BlueRobin services communicate with each other, including synchronous API calls and asynchronous event-driven messaging.

C4 Container View

C4Context
    title BlueRobin System Context

    Person(user, "User", "Document owner who uploads, searches, and asks questions")
    
    System_Boundary(bluerobin, "BlueRobin System") {
        Container(web, "Blazor Web", ".NET 10, Blazor Server", "Server-rendered UI with real-time updates")
        Container(api, "Archives API", ".NET 10, FastEndpoints", "REST API for document operations")
        Container(workers, "Archives Workers", ".NET 10, BackgroundService", "Async document processing pipeline")
    }

    System_Ext(authelia, "Authelia", "OIDC Identity Provider")
    System_Ext(openai, "OpenAI/Azure", "Cloud LLM for complex tasks")

    Rel(user, web, "Uses", "HTTPS")
    Rel(web, api, "Calls", "REST/HTTPS")
    Rel(web, authelia, "Authenticates", "OIDC")
    Rel(api, authelia, "Validates", "JWT")
    Rel(api, openai, "Generates", "HTTPS")
    Rel(workers, openai, "Analyzes", "HTTPS")

Service Communication Matrix

flowchart TB
    subgraph Frontend["Frontend Layer"]
        Web["Blazor Web
:8080"]
    end

    subgraph API["API Layer"]
        ArchivesAPI["Archives API
:8080"]
    end

    subgraph Workers["Worker Layer"]
        OcrW["OCR Worker"]
        AnalysisW["Analysis Worker"]
        EmbeddingW["Embedding Workers"]
        NerW["Entity Worker"]
        GraphW["Graph Worker"]
    end

    subgraph Data["Data Layer"]
        PG[(PostgreSQL
:5432)]
        Qdrant[(Qdrant
:6334)]
        MinIO[(MinIO
:9000)]
        FalkorDB[(FalkorDB
:6379)]
    end

    subgraph Messaging["Messaging Layer"]
        NATS{{"NATS JetStream
:4222"}}
    end

    subgraph AI["AI Layer"]
        Ollama["Ollama
:11434"]
        Docling["Docling
:8080"]
        Spacy["Spacy
:8080"]
    end

    %% Sync connections
    Web -->|REST| ArchivesAPI
    ArchivesAPI -->|SQL| PG
    ArchivesAPI -->|gRPC| Qdrant
    ArchivesAPI -->|S3| MinIO
    ArchivesAPI -->|HTTP| Ollama
    ArchivesAPI -->|Cypher| FalkorDB

    %% Async connections (pub/sub)
    ArchivesAPI -.->|Publish| NATS
    Web -.->|Subscribe| NATS
    
    NATS -.->|Consume| OcrW
    NATS -.->|Consume| AnalysisW
    NATS -.->|Consume| EmbeddingW
    NATS -.->|Consume| NerW
    NATS -.->|Consume| GraphW

    OcrW -.->|Publish| NATS
    AnalysisW -.->|Publish| NATS
    EmbeddingW -.->|Publish| NATS
    NerW -.->|Publish| NATS
    GraphW -.->|Publish| NATS

    %% Worker to data
    OcrW -->|HTTP| Docling
    OcrW -->|S3| MinIO
    OcrW -->|SQL| PG
    
    AnalysisW -->|HTTP| Ollama
    AnalysisW -->|SQL| PG
    
    EmbeddingW -->|HTTP| Ollama
    EmbeddingW -->|gRPC| Qdrant
    
    NerW -->|HTTP| Spacy
    NerW -->|SQL| PG
    
    GraphW -->|Cypher| FalkorDB

    style Frontend fill:#eee9f5
    style API fill:#fdf8ea
    style Workers fill:#ddd4ed
    style Data fill:#edf5f6
    style Messaging fill:#f8eded
    style AI fill:#faf2d0

Protocol Details

Communication Patterns

flowchart LR
    subgraph Sync["Synchronous (Request/Response)"]
        direction TB
        A1[Client] -->|Request| A2[Service]
        A2 -->|Response| A1
        A3["✓ REST APIs
✓ gRPC calls
✓ Database queries"]
    end

    subgraph Async["Asynchronous (Event-Driven)"]
        direction TB
        B1[Publisher] -->|Event| B2[Message Broker]
        B2 -->|Deliver| B3[Consumer]
        B4["✓ Document events
✓ Processing pipeline
✓ Real-time updates"]
    end

    subgraph Hybrid["Hybrid (CQRS)"]
        direction TB
        C1[Command] -->|Write| C2[API]
        C2 -->|Event| C3[NATS]
        C3 -->|Update| C4[Read Model]
        C5[Query] -->|Read| C4
    end

    style Sync fill:#eee9f5
    style Async fill:#fdf8ea
    style Hybrid fill:#edf5f6

Service Dependencies

graph TD
    subgraph Critical["Critical Path"]
        API --> PG
        API --> MinIO
        Web --> API
    end

    subgraph Processing["Processing Path"]
        Workers --> NATS
        Workers --> Ollama
        Workers --> Qdrant
    end

    subgraph Optional["Optional/Degraded"]
        API -.-> FalkorDB
        API -.-> Qdrant
        Workers -.-> Spacy
    end

    style Critical fill:#f0dbd8
    style Processing fill:#faf2d0
    style Optional fill:#d5eef0

Resilience Patterns