Kubernetes Deployment Architecture

This diagram shows the BlueRobin deployment topology on a K3s cluster, including namespace organization, service communication, and infrastructure components.

Cluster Overview

flowchart TB
    subgraph Internet["🌐 Internet"]
        User[("👤 User")]
        GitHub["GitHub
(Webhooks)"]
    end

    subgraph LaptopDev["💻 Developer Laptop (off-cluster — ADR-034)"]
        DevStack["Dev environment
local PostgreSQL · NATS · API/Web
(prod is the only in-cluster env)"]
    end

    subgraph Cluster["K3s Cluster (bluerobin-local)"]
        subgraph Gateway["🚪 Gateway Layer"]
            Traefik["Traefik Ingress
*.bluerobin.local"]
            CertManager["cert-manager
Let's Encrypt"]
        end

        subgraph Auth["🔐 Auth Layer"]
            Authelia["Authelia
OIDC Provider
auth.bluerobin.local"]
        end

        subgraph AppsProd["📦 archives-prod (prod-only, in-cluster)"]
            direction TB
            WebProd["Archives Web
Blazor Server
replicas: 2"]
            APIProd["Archives API
FastEndpoints
replicas: 2"]
            WorkersProd["Archives Workers
BackgroundService
replicas: 1"]
        end

        subgraph DataLayer["💾 data-layer (Shared)"]
            direction TB
            
            subgraph Databases["Databases"]
                PG["PostgreSQL
CNPG Cluster
3 instances"]
                PGBouncer["PgBouncer
Connection Pool"]
                Qdrant["Qdrant
Vector DB"]
                FalkorDB["FalkorDB
Graph DB"]
            end

            subgraph Storage["Storage"]
                MinIO["MinIO
Object Storage
SSE-KMS"]
                KES["KES
Key Server"]
            end

            subgraph Messaging["Messaging"]
                NATS["NATS JetStream
3 replicas"]
            end
        end

        subgraph AI["🤖 ai"]
            direction TB
            Ollama["Ollama
GPU Node
8 embedding models"]
            Docling["Docling OCR
PDF extraction"]
            Spacy["Spacy NER
Entity extraction"]
        end

        subgraph Platform["⚙️ platform"]
            direction TB
            Flux["Flux CD
GitOps"]
            SigNoz["SigNoz
Observability"]
            Infisical["Infisical
Secrets"]
            ARC["Action Runner
Controller"]
        end
    end

    User -->|HTTPS| Traefik
    GitHub -->|Webhooks| Traefik
    Traefik -->|TLS| CertManager
    Traefik -->|/| WebProd
    Traefik -->|/api| APIProd
    Traefik -->|auth.*| Authelia

    WebProd -->|REST| APIProd
    WebProd -->|OIDC| Authelia
    APIProd -->|OIDC| Authelia

    APIProd -->|SQL| PGBouncer
    APIProd -->|gRPC| Qdrant
    APIProd -->|S3| MinIO
    APIProd -->|Pub/Sub| NATS
    APIProd -->|HTTP| Ollama
    APIProd -->|Cypher| FalkorDB

    WorkersProd -->|Consume| NATS
    WorkersProd -->|SQL| PGBouncer
    WorkersProd -->|gRPC| Qdrant
    WorkersProd -->|S3| MinIO
    WorkersProd -->|HTTP| Ollama
    WorkersProd -->|HTTP| Docling
    WorkersProd -->|HTTP| Spacy
    WorkersProd -->|Cypher| FalkorDB

    PGBouncer --> PG

    MinIO -.->|Keys| KES

    Flux -->|Deploy| AppsProd
    ARC -->|Build| AppsProd

    DevStack -.->|Tailscale
shared data-layer| DataLayer

    style Gateway fill:#eee9f5
    style Auth fill:#fdf8ea
    style AppsProd fill:#edf5f6
    style LaptopDev fill:#ddd4ed
    style DataLayer fill:#f8eded
    style AI fill:#faf2d0
    style Platform fill:#d5eef0

Network Topology

flowchart LR
    subgraph External["External Network"]
        Internet["Internet
0.0.0.0/0"]
    end

    subgraph MetalLB["MetalLB Pool
192.168.0.50-60"]
        LB["LoadBalancer IP
192.168.0.50"]
    end

    subgraph Tailscale["Tailscale Network
100.x.x.x"]
        DevMachine["Dev Laptop
(off-cluster dev env)
100.x.x.1"]
    end

    subgraph ClusterNetwork["Cluster Network"]
        subgraph Services["ClusterIP Services"]
            WebSvc["web.archives-prod.svc
:8080"]
            APISvc["api.archives-prod.svc
:8080"]
            PGSvc["postgres.data-layer.svc
:5432"]
            NATSSvc["nats.data-layer.svc
:4222"]
            QdrantSvc["qdrant.data-layer.svc
:6334"]
            MinIOSvc["minio.data-layer.svc
:9000"]
        end

        subgraph NodePorts["NodePort Services (Dev)"]
            PGNP["PostgreSQL :30432"]
            NATSNP["NATS :30422"]
            QdrantNP["Qdrant :30634"]
        end
    end

    Internet --> LB
    LB --> WebSvc
    LB --> APISvc
    DevMachine -.->|Tailscale| PGNP
    DevMachine -.->|Tailscale| NATSNP
    DevMachine -.->|Tailscale| QdrantNP

Resource Allocation

pie showData
    title CPU Allocation (millicores)
    "PostgreSQL (3x)" : 3000
    "Ollama (GPU)" : 2000
    "Archives API (2x)" : 1000
    "Archives Web (2x)" : 1000
    "Archives Workers" : 500
    "NATS (3x)" : 600
    "Qdrant" : 500
    "MinIO" : 500
    "Other" : 900

Namespace Purpose

Namespace	Purpose	Environment Isolation
`archives-prod`	Production workloads (the only in-cluster app env — ADR-034)	Prod databases, buckets
`data-layer`	Shared infrastructure (also reachable from the laptop dev env over Tailscale)	`prod.` prefixes
`ai`	AI/ML services	Shared models
`platform`	Platform services	N/A
`flux-system`	GitOps controller	N/A
`cert-manager`	TLS certificates	N/A

High Availability Configuration

Component	Replicas	HA Strategy
PostgreSQL	3	CNPG streaming replication
NATS	3	Clustered JetStream
Archives API	2	Load balanced
Archives Web	2	Session affinity
Workers	1	Single consumer per queue
Qdrant	1	Persistent volume
Ollama	1	GPU singleton

Service Discovery

All services use Kubernetes DNS (CoreDNS):

Pattern: {service}.{namespace}.svc.cluster.local
Example: nats.data-layer.svc.cluster.local:4222