# platformbuilds/mirador-core architecture

> Architecture diagram of the GitHub repository platformbuilds/mirador-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/platformbuilds/mirador-core
- Repository: https://github.com/platformbuilds/mirador-core

## Overview

##### Project Type & Purpose
- This is a Go-based backend microservice (“mirador-core”) in a larger observability platform. It exposes a unified REST+WebSocket API (Gin) for metrics, logs, traces, AI-driven analysis (predict/RCA/alerts), schema definitions, and real-time streams.
- It orchestrates between clients (UI, Prometheus, CLI), external backends (VictoriaMetrics ecosystem, search engines, AI engines), and caches/sessions (Valkey/Redis cluster).

##### File Structure Analysis
- Top-level:
- cmd/server & cmd/schemactl – entrypoints for API server & CLI tool
- api/ – OpenAPI/Swagger definitions & Postman collection
- internal/ – application code organized by domain:
– api (handlers, middleware, server)
– config, discovery, grpc (clients + protobufs)
– services (business logic for metrics, logs, traces, AI, schema store, notifications)
– repo/storage (Weaviate for schema persistence)
– utils, metrics, monitoring, models
- pkg/ – reusable packages (auth, caching, logging)
- deployments/ & chart/ – Helm chart, Kubernetes yamls, local-dev Docker Compose
- Makefile, Dockerfile, CI workflows – build/test/deploy automation
- This layered layout reveals a clear separation:
- HTTP/gRPC ingress → middleware → handlers → services → backends (HTTP+gRPC) + cache + schema store.

##### README Insights
- Confirms main components: REST API, WebSocket streams, gRPC AI engines (Predict, RCA, Alert), VictoriaMetrics (metrics, logs, traces), optional search engines (Lucene & Bleve), Valkey cluster for caching/sessions, Weaviate for schema definitions, enterprise auth (LDAP/AD, OAuth 2.0, RBAC), external notifications (Slack/Teams/SMTP).

- Clients:
- Browser-based UI (mirador-ui)
- Prometheus scraper
- CLI (schemactl) / engineers via CURL/Postman
- Ingress Layer:
- Load Balancer / API Gateway / Ingress Controller (TLS termination)
- mirador-core Service:
- Gin HTTP Server + WebSocket endpoint
- Middleware (Auth, RBAC, Rate Limiter, Request Logger, Metrics)
- Handlers (MetricsQL, LogsQL, Traces, Predict, RCA, Alerts, Schema, Sessions)
- Internal Services Layer
– VictoriaMetricsServices (metrics/logs/traces)
– gRPC Clients (Predict/RCA/Alert engines)
– NotificationService
- Caching & Sessions:
- Valkey cluster (Redis-based) for query result caching, sessions, rate limiting counters
- Persistence & Backends:
- VictoriaMetrics ecosystem: VM-Select (metrics), VL-Select (logs), VT-Select (traces/Jaeger)
- Search Engines: Lucene service or embedded Bleve engine
- Weaviate for schema definitions
- Identity/Authentication: LDAP/AD or OAuth/OIDC provider
- External Notification endpoints: Slack, MS Teams, SMTP
- Clients → Ingress/LB → mirador-core HTTP
- mirador-core Handlers → Internal Services
- Services →
- VM/VL/VT HTTP endpoints
- gRPC to Predict/RCA/Alert engines
- Weaviate HTTP API
- Valkey cluster (Redis)
- External notifier webhooks
- mirador-core → WebSocket streams back to UI
- Prometheus → mirador-core `/metrics`
c. Architectural Patterns & Principles:
- Layered architecture (HTTP API → middleware → handlers → services → backends)
- Dependency injection via configuration (Viper)
- Stateless service design for horizontal scaling
- Cache-aside pattern with Valkey cluster for performance
- Façade over multiple metric/log/trace sources – fan-out + aggregation
- Pluggable search engine strategy (strategy pattern for Lucene vs. Bleve)
- Bulk upload safety controls (in-memory CSV handling)
d. Key Technologies & Libraries:
- Go / Gin HTTP framework / WebSocket
- gRPC + Protocol Buffers (AI engines)
- VictoriaMetrics (PromQL/MetricsQL), VictoriaLogs (LogsQL), VictoriaTraces (Jaeger API)
- Bleve & Lucene query translation
- Valkey cluster (Redis) caching
- Weaviate client (Go)
- LDAP/AD & OAuth 2.0 (enterprise auth), JWT sessions
- Helm, Kubernetes, Docker, Makefile for deployment

##### Final Checklist
- Essential components and interactions without over-splitting trivial modules.
- Keep it at a single page/slide level; use callouts or expanded inset for complex sub-flows (e.g., AI analysis pipeline).
- Validate with stakeholders (DevOps, AI team) that ports, protocols, and dependencies are accurate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        UI["Browser UI"]:::infra
        Prom["Prometheus Scraper"]:::infra
        CLI["CLI / schemactl"]:::infra
    end

    %% Ingress Layer
    LB["Load Balancer / API Gateway (TLS)"]:::infra

    %% Core Service
    subgraph "mirador-core Service" 
        direction TB

        Server["Gin HTTP Server & WebSocket"]:::core
        click Server "https://github.com/platformbuilds/mirador-core/blob/main/cmd/server/main.go"
        click Server "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/server.go"

        subgraph "Middleware" 
            direction TB
            Auth["Auth / RBAC"]:::core
            RateLim["Rate Limiter"]:::core
            Logger["Request Logger"]:::core
            MetricsM["Metrics Middleware"]:::core
            SessionM["Session Middleware"]:::core
            click Auth "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/middleware/auth.middleware.go"
            click RateLim "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/middleware/rate_limiter.middleware.go"
            click Logger "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/middleware/request_logger.middleware.go"
            click MetricsM "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/middleware/metrics.middleware.go"
            click SessionM "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/middleware/session.go"
        end

        subgraph "Handlers" 
            direction TB
            HL_M["MetricsQL Handler"]:::core
            HL_L["LogsQL Handler"]:::core
            HL_T["Traces Handler"]:::core
            HL_P["Predict Handler"]:::core
            HL_R["RCA Handler"]:::core
            HL_A["Alert Handler"]:::core
            HL_S["Schema Handler"]:::core
            HL_SS["Session Handler"]:::core
            HL_WS["WebSocket Handler"]:::core
            click HL_M "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/handlers/metricsql.handler.go"
            click HL_L "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/handlers/logs_handlers.go"
            click HL_T "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/handlers/traces.handler.go"
            click HL_P "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/handlers/predict.handler.go"
            click HL_R "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/handlers/rca.handler.go"
            click HL_A "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/handlers/alert.handler.go"
            click HL_S "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/handlers/schema.handler.go"
            click HL_SS "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/handlers/session.handler.go"
            click HL_WS "https://github.com/platformbuilds/mirador-core/blob/main/internal/api/websocket/websocket.go"
        end

        subgraph "Internal Services" 
            direction TB
            VMetrics["VictoriaMetrics Services"]:::core
            click VMetrics "https://github.com/platformbuilds/mirador-core/blob/main/internal/services/victoria_metrics.service.go"
            VLogs["VictoriaLogs Service"]:::core
            click VLogs "https://github.com/platformbuilds/mirador-core/blob/main/internal/services/victoria_logs.service.go"
            VTraces["VictoriaTraces Service"]:::core
            click VTraces "https://github.com/platformbuilds/mirador-core/blob/main/internal/services/victoria_traces.service.go"
            AI_P["gRPC Predict-Engine Client"]:::core
            click AI_P "https://github.com/platformbuilds/mirador-core/blob/main/internal/grpc/clients/predict_engine_client.go"
            AI_R["gRPC RCA-Engine Client"]:::core
            click AI_R "https://github.com/platformbuilds/mirador-core/blob/main/internal/grpc/clients/rca_engine_client.go"
            AI_A["gRPC Alert-Engine Client"]:::core
            click AI_A "https://github.com/platformbuilds/mirador-core/blob/main/internal/grpc/clients/alert_engine_client.go"
            Notify["Notification Service"]:::core
            click Notify "https://github.com/platformbuilds/mirador-core/blob/main/internal/services/notification.service.go"
            SSO["SSO / Auth Service"]:::core
            click SSO "https://github.com/platformbuilds/mirador-core/blob/main/internal/services/sso.service.go"
        end
    end

    %% Caching & Sessions
    Cache["Valkey Cluster (Redis)"]:::cache
    click Cache "https://github.com/platformbuilds/mirador-core/blob/main/pkg/cache/valkey_cluster.go"

    %% Schema Persistence
    Weav["Weaviate Schema Store"]:::cache
    click Weav "https://github.com/platformbuilds/mirador-core/blob/main/internal/repo/schema_repo.go"
    click Weav "https://github.com/platformbuilds/mirador-core/blob/main/internal/repo/schema_weaviate.go"

    %% External Backends
    subgraph "External Backends"
        direction TB
        VM["VM-Select (8481)"]:::external
        VL["VL-Select (8081)"]:::external
        VT["VT-Select (14268)"]:::external
        Lucene["Lucene Search"]:::external
        Bleve["Embedded Bleve"]:::external
        IDP["LDAP/AD or OAuth2 Provider"]:::external
        Slack["Slack Webhook"]:::external
        Teams["MS Teams Webhook"]:::external
        SMTP["SMTP Endpoint"]:::external
        PredictE["Predict Engine (9091)"]:::external
        RCAE["RCA Engine (9092)"]:::external
        ARTE["Alert Engine (9093)"]:::external
    end

    %% Connections
    UI -->|HTTP / WebSocket| LB
    Prom -->|HTTP / Metrics| LB
    CLI -->|HTTP| LB

    LB -->|HTTP| Server

    Server -->|executes| Auth
    Auth --> RateLim --> Logger --> MetricsM --> SessionM --> HL_M
    SessionM --> HL_SS
    Logger --> HL_L
    HL_M --> VMetrics
    HL_L --> VLogs
    HL_T --> VTraces
    HL_P --> AI_P
    HL_R --> AI_R
    HL_A --> AI_A
    HL_S --> Weav
    HL_SS --> Cache
    HL_WS --> UI

    VMetrics --> VM
    VLogs --> VL
    VTraces --> VT

    AI_P -->|gRPC| PredictE
    AI_R -->|gRPC| RCAE
    AI_A -->|gRPC| ARTE

    Notify --> Slack
    Notify --> Teams
    Notify --> SMTP

    SSO --> IDP

    %% Classes
    classDef core fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef external fill:#E0FFE0,stroke:#333,stroke-width:1px
    classDef cache fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px
```
