# im-vishesh15th/distri-kv architecture

> Architecture diagram of the GitHub repository im-vishesh15th/distri-kv, 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/im-vishesh15th/distri-kv
- Repository: https://github.com/im-vishesh15th/distri-kv

## Overview

DistriKV is a distributed key-value database with a hosted, tenant-isolated service and web console. Users sign up or log in, manage API keys and quotas, then submit key-value operations through the gateway; requests are routed to sharded Raft groups and applied to replicated state machines. The graph preserves the documented consensus, storage, sharding, observability, and fault-analysis capabilities. Backend relationships are mainly documented in the README; unsampled implementation links are marked dashed where their exact call path is not shown.

Main entry points: [`console/src/context/AuthContext.tsx`](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/context/AuthContext.tsx) (Session and Auth), [`console/src/App.tsx`](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/App.tsx) (Web Console), [`internal/gateway/gateway.go`](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/gateway.go) (Gateway Service), [`console/src/components/ui`](https://github.com/im-vishesh15th/distri-kv/tree/main/console/src/components/ui) (Shared UI Components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and Console"]
  node_console["Web Console<br/>[App.tsx]"]
  node_auth_context["Session and Auth<br/>[AuthContext.tsx]"]
  node_console_dashboard["Tenant Dashboard<br/>[DashboardPage.tsx]"]
  node_console_keys["API Key Management<br/>[KeysPage.tsx]"]
  node_console_key_detail["Key Details<br/>[KeyDetailPage.tsx]"]
  node_console_admin["Admin Tenant Views"]
  node_console_usage["Usage Views<br/>[UsagePage.tsx]"]
  node_console_ui["Shared UI Components"]
  node_sdk["Go Client SDK<br/>[client.go]"]
end

subgraph group_service["Hosted Service"]
  node_gateway_entry["Gateway Service<br/>[gateway.go]"]
  node_gateway_control["Tenant and Key Control<br/>[control.go]"]
  node_gateway_storage[("Gateway Persistence<br/>[storage.go]")]
  node_gateway_usage["Usage and Metrics<br/>[metrics.go]"]
  node_server["KV Service API<br/>[service.go]"]
end

subgraph group_distribution["Sharding and Consensus"]
  node_sharding["Fixed-Slot Router<br/>[shard.go]"]
  node_multiraft["Multi-Raft Host<br/>[cluster.go]"]
  node_raft["Raft Consensus<br/>[raft.go]"]
  node_transport["gRPC Transport<br/>[real.go]"]
end

subgraph group_storage["Replicated Storage"]
  node_raftlog[("Persistent Raft Log<br/>[raftlog.go]")]
  node_kv_sm["KV State Machine<br/>[sm.go]"]
  node_kv_engine["KV Engine<br/>[kv.go]"]
end

subgraph group_operations["Reliability and Operations"]
  node_sim_network["Fault Simulation<br/>[network.go]"]
  node_lincheck["Linearizability Checker<br/>[lincheck.go]"]
  node_history["Operation History<br/>[history.go]"]
  node_node_metrics["Node Metrics<br/>[nodemetrics.go]"]
end

node_user(("Tenant / Operator"))

node_user -->|"uses console"| node_console
node_console -->|"routes through"| node_auth_context
node_console -->|"routes to"| node_console_dashboard
node_console -->|"routes to"| node_console_keys
node_console -->|"routes to"| node_console_key_detail
node_console -->|"routes to"| node_console_admin
node_console_dashboard -->|"requests API"| node_auth_context
node_console_keys -->|"requests API"| node_auth_context
node_console_key_detail -->|"requests API"| node_auth_context
node_console_usage -->|"requests API"| node_auth_context
node_console_admin -->|"requests API"| node_auth_context
node_console_dashboard -->|"renders with"| node_console_ui
node_console_keys -->|"renders with"| node_console_ui
node_console_key_detail -->|"renders with"| node_console_ui
node_console_admin -->|"renders with"| node_console_ui
node_console_usage -->|"renders with"| node_console_ui
node_user -->|"submits operations"| node_sdk
node_auth_context -.->|"calls HTTP API"| node_gateway_entry
node_sdk -->|"calls KV API"| node_server
node_gateway_entry -.->|"authenticates tenants"| node_gateway_control
node_gateway_entry -.->|"persists service data"| node_gateway_storage
node_gateway_entry -.->|"records usage"| node_gateway_usage
node_gateway_entry -->|"forwards KV requests"| node_server
node_server -->|"routes key slots"| node_sharding
node_sharding -->|"selects group"| node_multiraft
node_multiraft -->|"hosts groups"| node_raft
node_raft -->|"persists log"| node_raftlog
node_raft -->|"applies commits"| node_kv_sm
node_kv_sm -->|"executes commands"| node_kv_engine
node_raft -.->|"exchanges messages"| node_transport
node_sim_network -.->|"simulates faults"| node_transport
node_history -.->|"checks histories"| node_lincheck
node_multiraft -.->|"emits metrics"| node_node_metrics

click node_console "https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/App.tsx"
click node_auth_context "https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/context/AuthContext.tsx"
click node_console_dashboard "https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/dashboard/DashboardPage.tsx"
click node_console_keys "https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/keys/KeysPage.tsx"
click node_console_key_detail "https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/keys/KeyDetailPage.tsx"
click node_console_admin "https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/admin/AdminTenantDetailPage.tsx"
click node_console_usage "https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/usage/UsagePage.tsx"
click node_console_ui "https://github.com/im-vishesh15th/distri-kv/tree/main/console/src/components/ui"
click node_sdk "https://github.com/im-vishesh15th/distri-kv/blob/main/pkg/client/client.go"
click node_gateway_entry "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/gateway.go"
click node_gateway_control "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/control.go"
click node_gateway_storage "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/storage.go"
click node_gateway_usage "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/metrics.go"
click node_server "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/server/service.go"
click node_sharding "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/shard/shard.go"
click node_multiraft "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/multiraft/cluster.go"
click node_raft "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/raft/raft.go"
click node_raftlog "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/raftlog/raftlog.go"
click node_kv_sm "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/kv/sm.go"
click node_kv_engine "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/kv/kv.go"
click node_transport "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/transport/grpc/real.go"
click node_sim_network "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/transport/sim/network.go"
click node_lincheck "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/lincheck/lincheck.go"
click node_history "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/history/history.go"
click node_node_metrics "https://github.com/im-vishesh15th/distri-kv/blob/main/internal/nodemetrics/nodemetrics.go"

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_console,node_auth_context,node_console_dashboard,node_console_keys,node_console_key_detail,node_console_admin,node_console_usage,node_console_ui,node_sdk toneBlue
class node_gateway_entry,node_gateway_control,node_gateway_storage,node_gateway_usage,node_server toneAmber
class node_sharding,node_multiraft,node_raft,node_transport toneMint
class node_raftlog,node_kv_sm,node_kv_engine toneRose
class node_sim_network,node_lincheck,node_history,node_node_metrics,node_user toneIndigo
```

## Components

### Clients and Console

- [Web Console](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/App.tsx): `console/src/App.tsx`
- [Session and Auth](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/context/AuthContext.tsx): `console/src/context/AuthContext.tsx`
- [Tenant Dashboard](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/dashboard/DashboardPage.tsx): `console/src/pages/dashboard/DashboardPage.tsx`
- [API Key Management](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/keys/KeysPage.tsx): `console/src/pages/keys/KeysPage.tsx`
- [Key Details](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/keys/KeyDetailPage.tsx): `console/src/pages/keys/KeyDetailPage.tsx`
- [Admin Tenant Views](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/admin/AdminTenantDetailPage.tsx): `console/src/pages/admin/AdminTenantDetailPage.tsx`
- [Usage Views](https://github.com/im-vishesh15th/distri-kv/blob/main/console/src/pages/usage/UsagePage.tsx): `console/src/pages/usage/UsagePage.tsx`
- [Shared UI Components](https://github.com/im-vishesh15th/distri-kv/tree/main/console/src/components/ui): `console/src/components/ui`
- [Go Client SDK](https://github.com/im-vishesh15th/distri-kv/blob/main/pkg/client/client.go): `pkg/client/client.go`

### Hosted Service

- [Gateway Service](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/gateway.go): `internal/gateway/gateway.go`
- [Tenant and Key Control](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/control.go): `internal/gateway/control.go`
- [Gateway Persistence](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/storage.go): `internal/gateway/storage.go`
- [Usage and Metrics](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/gateway/metrics.go): `internal/gateway/metrics.go`
- [KV Service API](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/server/service.go): `internal/server/service.go`

### Sharding and Consensus

- [Fixed-Slot Router](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/shard/shard.go): `internal/shard/shard.go`
- [Multi-Raft Host](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/multiraft/cluster.go): `internal/multiraft/cluster.go`
- [Raft Consensus](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/raft/raft.go): `internal/raft/raft.go`
- [gRPC Transport](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/transport/grpc/real.go): `internal/transport/grpc/real.go`

### Replicated Storage

- [Persistent Raft Log](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/raftlog/raftlog.go): `internal/raftlog/raftlog.go`
- [KV State Machine](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/kv/sm.go): `internal/kv/sm.go`
- [KV Engine](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/kv/kv.go): `internal/kv/kv.go`

### Reliability and Operations

- [Fault Simulation](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/transport/sim/network.go): `internal/transport/sim/network.go`
- [Linearizability Checker](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/lincheck/lincheck.go): `internal/lincheck/lincheck.go`
- [Operation History](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/history/history.go): `internal/history/history.go`
- [Node Metrics](https://github.com/im-vishesh15th/distri-kv/blob/main/internal/nodemetrics/nodemetrics.go): `internal/nodemetrics/nodemetrics.go`

### Other components

- **Tenant / Operator**

## Connections

- Tenant / Operator → Web Console: uses console (evidence: `console/src/App.tsx`)
- Web Console → Session and Auth: routes through (evidence: `console/src/App.tsx`)
- Web Console → Tenant Dashboard: routes to (evidence: `console/src/App.tsx`)
- Web Console → API Key Management: routes to (evidence: `console/src/App.tsx`)
- Web Console → Key Details: routes to (evidence: `console/src/App.tsx`)
- Web Console → Admin Tenant Views: routes to (evidence: `console/src/App.tsx`)
- Tenant Dashboard → Session and Auth: requests API (evidence: `console/src/pages/dashboard/DashboardPage.tsx`)
- API Key Management → Session and Auth: requests API (evidence: `console/src/pages/keys/KeysPage.tsx`)
- Key Details → Session and Auth: requests API (evidence: `console/src/pages/keys/KeyDetailPage.tsx`)
- Usage Views → Session and Auth: requests API (evidence: `console/src/pages/usage/UsagePage.tsx`)
- Admin Tenant Views → Session and Auth: requests API (evidence: `console/src/pages/admin/AdminTenantDetailPage.tsx`)
- Tenant Dashboard → Shared UI Components: renders with (evidence: `console/src/pages/dashboard/DashboardPage.tsx`)
- API Key Management → Shared UI Components: renders with (evidence: `console/src/pages/keys/KeysPage.tsx`)
- Key Details → Shared UI Components: renders with (evidence: `console/src/pages/keys/KeyDetailPage.tsx`)
- Admin Tenant Views → Shared UI Components: renders with (evidence: `console/src/pages/admin/AdminTenantDetailPage.tsx`)
- Usage Views → Shared UI Components: renders with (evidence: `console/src/pages/usage/UsagePage.tsx`)
- Tenant / Operator → Go Client SDK: submits operations (evidence: `README.md`)
- Session and Auth → Gateway Service: calls HTTP API
- Go Client SDK → KV Service API: calls KV API (evidence: `README.md`)
- Gateway Service → Tenant and Key Control: authenticates tenants
- Gateway Service → Gateway Persistence: persists service data
- Gateway Service → Usage and Metrics: records usage
- Gateway Service → KV Service API: forwards KV requests (evidence: `README.md`)
- KV Service API → Fixed-Slot Router: routes key slots (evidence: `README.md`)
- Fixed-Slot Router → Multi-Raft Host: selects group (evidence: `README.md`)
- Multi-Raft Host → Raft Consensus: hosts groups (evidence: `README.md`)
- Raft Consensus → Persistent Raft Log: persists log (evidence: `README.md`)
- Raft Consensus → KV State Machine: applies commits (evidence: `README.md`)
- KV State Machine → KV Engine: executes commands (evidence: `internal/kv/sm.go`)
- Raft Consensus → gRPC Transport: exchanges messages
- Fault Simulation → gRPC Transport: simulates faults
- Operation History → Linearizability Checker: checks histories
- Multi-Raft Host → Node Metrics: emits metrics
