# vdaas/vald architecture

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

- Interactive diagram: https://gitdiagram.com/vdaas/vald
- Repository: https://github.com/vdaas/vald

## Overview

##### Main Architectural Layers
- Frontend / Client Devices: These represent the applications or clients that send search/insertion requests (for example, via SDKs or REST/gRPC calls).
- API Gateways: Vald has gateways (both load-balancer and filter gateways) that front external requests. They provide routing, load balancing, and potentially authentication.
- Core Search Components:
– Vald Agent(s): The heart of the system where the ANN search happens using engines like NGT (and optionally Faiss). There are two variants: the standard “Agent” and the “Agent Sidecar” which operate in tandem.
– Discoverer: A separate component that monitors cluster state and health for dynamic clustering.
– Index Manager: Responsible for tasks like index correction (saving, deleting, rotating) that help in maintaining the vector index over time.
- Orchestration and Management:
– Helm Operator and related charts: These are used for deploying, managing, and scaling the system on Kubernetes.
- Supporting Services: This includes data compression, backup mechanisms, observability/metrics (gRPC, Prometheus, Jaeger, etc.), and configuration management.

##### File Structure and README Insights
- The “cmd” and “pkg” directories show multiple services (agent, index, discoverer, gateway, manager, tools) while “apis”, “internal”, and “docker” indicate a well-modularized microservice architecture.
- The README and assets provide visual overviews and detailed descriptions of how these components interoperate (e.g., the “Vald Architecture Overview” image).

##### Relationships and Data Flow
- The Agent internally uses specialized ANN algorithms (NGT, Faiss, possibly integrated via packages such as “pkg/agent/core/ngt” or “pkg/agent/core/faiss”) to perform vector searches.
- Parallel to the Agent, the Discoverer service monitors the health and registration state of agents.
- The Index Manager interacts with Agents to perform correction, backup, and maintenance tasks on the indices.
- An orchestration layer (Helm Operator) and Kubernetes-related configurations show how these components are deployed, scaled, and managed.

##### Architectural Patterns & Design Principles
- Microservices: Each core function (agent, index correction, discoverer, gateway, manager) is implemented as a separate service, which can be scaled horizontally.
- Cloud-Native / Kubernetes: Emphasize that the services are designed for dynamic orchestration, auto-scaling, and resilience with health checks managed by Kubernetes.
- Modular design: Clear separation between network communication layers (gRPC APIs), core algorithms (NGT, Faiss usecases), and orchestration code.

- Clear labels for each component:
- “Client / SDK”
- “Gateway (LB & Filter)”
- “Vald Agent (NGT)” and optionally “Agent Sidecar”
- “Discoverer”
- “Index Manager”
- “Helm Operator / Deployment Manager”
- The flow of a search query from the Client to the Gateway to the Agent.
- Management or control flows from the Index Manager to the agents.
- Health and status reporting flows from the Agent to the Discoverer.
- Deployment control signals from the Helm Operator to the Kubernetes cluster.
- Microservices could be shown as rounded rectangles.
- Kubernetes-related elements can be enclosed in a “cluster” boundary.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Client Layer
    subgraph "External Client Layer"
        Client["Client / SDK"]:::client
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        Gateway["Gateway (LB & Filter)"]:::gateway
    end

    %% Core Search Components
    subgraph "Core Search Components"
        Agent["Vald Agent (NGT & Faiss)"]:::agent
        Sidecar["Agent Sidecar"]:::sidecar
        Discoverer["Discoverer"]:::discoverer
        IndexManager["Index Manager"]:::index
        Manager["Manager"]:::manager
    end

    %% Orchestration and Management
    subgraph "Orchestration and Management"
        Helm["Helm Operator / Deployment Manager"]:::operator
    end

    %% Connections between layers
    Client -->|"gRPC/REST"| Gateway
    Gateway -->|"gRPC"| Agent
    Agent -->|"sidecar_linkage"| Sidecar
    Agent -->|"health_status"| Discoverer
    IndexManager -->|"index_control"| Agent
    IndexManager -->|"index_control"| Sidecar
    Manager -->|"cluster_management"| IndexManager

    %% Deployment signals from Helm Operator to core components
    Helm -->|"deploy"| Gateway
    Helm -->|"deploy"| Agent
    Helm -->|"deploy"| Sidecar
    Helm -->|"deploy"| Discoverer
    Helm -->|"deploy"| IndexManager
    Helm -->|"deploy"| Manager

    %% Click Events for Vald Agent (NGT & Faiss)
    click Agent "https://github.com/vdaas/vald/tree/main/cmd/agent"
    click Agent "https://github.com/vdaas/vald/tree/main/pkg/agent/core/ngt"
    click Agent "https://github.com/vdaas/vald/tree/main/pkg/agent/core/faiss"
    click Agent "https://github.com/vdaas/vald/tree/main/dockers/agent"

    %% Click Events for Agent Sidecar
    click Sidecar "https://github.com/vdaas/vald/tree/main/cmd/agent/sidecar"
    click Sidecar "https://github.com/vdaas/vald/tree/main/pkg/agent/sidecar"
    click Sidecar "https://github.com/vdaas/vald/tree/main/dockers/agent/sidecar"

    %% Click Events for Discoverer
    click Discoverer "https://github.com/vdaas/vald/tree/main/cmd/discoverer"
    click Discoverer "https://github.com/vdaas/vald/tree/main/pkg/discoverer"
    click Discoverer "https://github.com/vdaas/vald/tree/main/dockers/discoverer"

    %% Click Events for Gateway
    click Gateway "https://github.com/vdaas/vald/tree/main/cmd/gateway"
    click Gateway "https://github.com/vdaas/vald/tree/main/pkg/gateway"
    click Gateway "https://github.com/vdaas/vald/tree/main/dockers/gateway"

    %% Click Events for Index Manager
    click IndexManager "https://github.com/vdaas/vald/tree/main/cmd/index"
    click IndexManager "https://github.com/vdaas/vald/tree/main/pkg/index"
    click IndexManager "https://github.com/vdaas/vald/tree/main/dockers/index"

    %% Click Events for Manager
    click Manager "https://github.com/vdaas/vald/tree/main/cmd/manager/index"
    click Manager "https://github.com/vdaas/vald/tree/main/pkg/manager/index"
    click Manager "https://github.com/vdaas/vald/tree/main/dockers/manager/index"

    %% Click Events for Helm Operator
    click Helm "https://github.com/vdaas/vald/tree/main/charts/vald-helm-operator"
    click Helm "https://github.com/vdaas/vald/tree/main/k8s/operator/helm"

    %% Styles
    classDef client fill:#a6cee3,stroke:#333,stroke-width:2px;
    classDef gateway fill:#b2df8a,stroke:#333,stroke-width:2px;
    classDef agent fill:#fdbf6f,stroke:#333,stroke-width:2px;
    classDef sidecar fill:#ff7f00,stroke:#333,stroke-width:2px;
    classDef discoverer fill:#cab2d6,stroke:#333,stroke-width:2px;
    classDef index fill:#ffff99,stroke:#333,stroke-width:2px;
    classDef manager fill:#1f78b4,stroke:#333,stroke-width:2px;
    classDef operator fill:#fb9a99,stroke:#333,stroke-width:2px;
```
