# mukilanmuthuvalathan/vault-object-storage architecture

> Architecture diagram of the GitHub repository mukilanmuthuvalathan/vault-object-storage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mukilanmuthuvalathan/vault-object-storage
- Repository: https://github.com/mukilanmuthuvalathan/vault-object-storage

## Overview

Vault is a distributed object store with an operator dashboard. A client submits an object operation to the HTTP gateway; the gateway routes it to the vault engine, which handles versioned metadata and storage, then returns the result. The engine coordinates Raft metadata, artifact transport, and background health and repair work. The README also describes placement, nearest-replica reads, erasure coding, rebalancing, tombstones, and integrity scans; those domain stages are represented at the engine boundary because their implementation files are not in the supplied tree. Links reflect shown calls or documented relationships.

Main entry points: [`src/core/vault-engine.js`](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/core/vault-engine.js) (Object workflows), [`src/server.js`](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/server.js) (HTTP server), [`src/storage/storage-client.js`](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/storage/storage-client.js) (Storage transport), [`src/integrations/gcs-mirror.js`](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/integrations/gcs-mirror.js) (GCS mirror)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Operator experience"]
  node_dashboard["Dashboard<br/>[app.js]"]
end

subgraph group_gateway["HTTP gateway"]
  node_http["HTTP server<br/>[server.js]"]
  node_auth["API key auth<br/>[auth.js]"]
  node_limiter["Rate limiter<br/>[rate-limiter.js]"]
end

subgraph group_engine["Vault engine"]
  node_vault["Object workflows<br/>[vault-engine.js]"]
  node_locks["Per-key locks<br/>[lock-manager.js]"]
  node_metadata[("Raft metadata<br/>[raft-metadata.js]")]
  node_storageclient["Storage transport<br/>[storage-client.js]"]
  node_storagenodes[("Storage nodes")]
end

subgraph group_operations["Cluster operations"]
  node_health["Health monitor<br/>[health-monitor.js]"]
  node_repair["Repair scheduler"]
  node_gcs["GCS mirror<br/>[gcs-mirror.js]"]
end

node_operator(("Client / operator"))
node_gcsservice[("Google Cloud Storage")]

node_operator -->|"submits requests"| node_http
node_operator -->|"uses dashboard"| node_dashboard
node_http -->|"serves static files"| node_dashboard
node_http -->|"routes object operations"| node_vault
node_http -->|"checks credentials"| node_auth
node_http -->|"mirrors writes"| node_gcs
node_vault -->|"serializes key writes"| node_locks
node_vault -->|"commits catalog"| node_metadata
node_vault -->|"transfers artifacts"| node_storageclient
node_storageclient -->|"sends artifact requests"| node_storagenodes
node_vault -->|"configures integrity scans"| node_health
node_vault -->|"schedules repairs"| node_repair
node_gcs -->|"uploads objects"| node_gcsservice

click node_dashboard "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/public/app.js"
click node_http "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/server.js"
click node_auth "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/gateway/auth.js"
click node_limiter "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/gateway/rate-limiter.js"
click node_vault "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/core/vault-engine.js"
click node_locks "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/core/lock-manager.js"
click node_metadata "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/control/raft-metadata.js"
click node_storageclient "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/storage/storage-client.js"
click node_storagenodes "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/storage/storage-node-server.js"
click node_health "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/background/health-monitor.js"
click node_repair "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/background/repair-scheduler.js"
click node_gcs "https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/integrations/gcs-mirror.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_operator toneBlue
class node_http,node_auth,node_limiter,node_gcsservice toneAmber
class node_vault,node_locks,node_metadata,node_storageclient,node_storagenodes toneMint
class node_health,node_repair,node_gcs toneRose
```

## Components

### Operator experience

- [Dashboard](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/public/app.js): `public/app.js`

### HTTP gateway

- [HTTP server](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/server.js): `src/server.js`
- [API key auth](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/gateway/auth.js): `src/gateway/auth.js`
- [Rate limiter](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/gateway/rate-limiter.js): `src/gateway/rate-limiter.js`

### Vault engine

- [Object workflows](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/core/vault-engine.js): `src/core/vault-engine.js`
- [Per-key locks](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/core/lock-manager.js): `src/core/lock-manager.js`
- [Raft metadata](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/control/raft-metadata.js): `src/control/raft-metadata.js`
- [Storage transport](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/storage/storage-client.js): `src/storage/storage-client.js`
- [Storage nodes](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/storage/storage-node-server.js): `src/storage/storage-node-server.js`

### Cluster operations

- [Health monitor](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/background/health-monitor.js): `src/background/health-monitor.js`
- [Repair scheduler](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/background/repair-scheduler.js): `src/background/repair-scheduler.js`
- [GCS mirror](https://github.com/mukilanmuthuvalathan/vault-object-storage/blob/main/src/integrations/gcs-mirror.js): `src/integrations/gcs-mirror.js`

### Other components

- **Client / operator**
- **Google Cloud Storage**

## Connections

- Client / operator → HTTP server: submits requests (evidence: `README.md`)
- Client / operator → Dashboard: uses dashboard (evidence: `README.md`)
- HTTP server → Dashboard: serves static files (evidence: `src/server.js`)
- HTTP server → Object workflows: routes object operations (evidence: `src/server.js`)
- HTTP server → API key auth: checks credentials (evidence: `src/server.js`)
- HTTP server → GCS mirror: mirrors writes (evidence: `src/server.js`)
- Object workflows → Per-key locks: serializes key writes (evidence: `src/core/vault-engine.js`)
- Object workflows → Raft metadata: commits catalog (evidence: `src/core/vault-engine.js`)
- Object workflows → Storage transport: transfers artifacts (evidence: `src/core/vault-engine.js`)
- Storage transport → Storage nodes: sends artifact requests (evidence: `src/storage/storage-client.js`)
- Object workflows → Health monitor: configures integrity scans (evidence: `src/core/vault-engine.js`)
- Object workflows → Repair scheduler: schedules repairs (evidence: `src/core/vault-engine.js`)
- GCS mirror → Google Cloud Storage: uploads objects (evidence: `src/integrations/gcs-mirror.js`)
