# jusxtdev/kv-store architecture

> Architecture diagram of the GitHub repository jusxtdev/kv-store, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jusxtdev/kv-store
- Repository: https://github.com/jusxtdev/kv-store

## Overview

This is a single-process HTTP key–value store. Clients use its JSON API to create, read, update, delete, list, or clear values; mutations are logged before the in-memory map changes. On startup, the application loads snapshot state and replays later WAL records, then periodically writes snapshots. Replication and inter-node communication are documented as future ideas, not implemented. The graph follows documented architecture and sampled source; some finer recovery and HTTP wiring details are not shown beyond those sources.

Main entry points: [`cmd/api/main.go`](https://github.com/jusxtdev/kv-store/blob/main/cmd/api/main.go) (API server), [`internal/snapshot/snapshot.go`](https://github.com/jusxtdev/kv-store/blob/main/internal/snapshot/snapshot.go) (Snapshot manager), [`internal/wal/wal.go`](https://github.com/jusxtdev/kv-store/blob/main/internal/wal/wal.go) (WAL operations), [`internal/repository/memory.go`](https://github.com/jusxtdev/kv-store/blob/main/internal/repository/memory.go) (In-memory store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_health["Health handler<br/>[health.go]"]
  node_kvhandlers["KV handlers<br/>[kv.go]"]
  node_responses["JSON responses<br/>[common.go]"]
end

subgraph group_storage["Key-Value Storage"]
  node_storeinterface["Store interface<br/>[interface.go]"]
  node_memory["In-memory store<br/>[memory.go]"]
end

subgraph group_durability["Durability and Recovery"]
  node_wal["WAL operations<br/>[wal.go]"]
  node_walrecord["WAL records<br/>[record.go]"]
  node_snapshot["Snapshot manager<br/>[snapshot.go]"]
  node_walfile[("wal.log")]
  node_snapshotfile[("snapshot.json")]
end

subgraph group_lifecycle["Application Lifecycle"]
  node_server["API server<br/>[main.go]"]
end

node_client(("HTTP client"))

node_client -->|"sends HTTP"| node_server
node_server -->|"routes health"| node_health
node_server -->|"routes KV"| node_kvhandlers
node_health -->|"writes JSON"| node_responses
node_kvhandlers -->|"calls operations"| node_storeinterface
node_kvhandlers -->|"writes JSON"| node_responses
node_memory -->|"implements"| node_storeinterface
node_memory -->|"appends mutations"| node_wal
node_wal -->|"parses records"| node_walrecord
node_wal -->|"appends and replays"| node_walfile
node_server -->|"opens and replays"| node_wal
node_server -->|"initializes and restores"| node_snapshot
node_server -->|"restores and enables logging"| node_memory
node_snapshot -->|"reads state"| node_memory
node_snapshot -->|"reads checkpoint"| node_wal
node_snapshot -->|"writes snapshot"| node_snapshotfile
node_snapshot -->|"loads snapshot"| node_snapshotfile
node_server -->|"triggers every 10 seconds"| node_snapshot

click node_server "https://github.com/jusxtdev/kv-store/blob/main/cmd/api/main.go"
click node_health "https://github.com/jusxtdev/kv-store/blob/main/internal/handler/health.go"
click node_kvhandlers "https://github.com/jusxtdev/kv-store/blob/main/internal/handler/kv.go"
click node_responses "https://github.com/jusxtdev/kv-store/blob/main/internal/handler/common.go"
click node_storeinterface "https://github.com/jusxtdev/kv-store/blob/main/internal/repository/interface.go"
click node_memory "https://github.com/jusxtdev/kv-store/blob/main/internal/repository/memory.go"
click node_wal "https://github.com/jusxtdev/kv-store/blob/main/internal/wal/wal.go"
click node_walrecord "https://github.com/jusxtdev/kv-store/blob/main/internal/wal/record.go"
click node_snapshot "https://github.com/jusxtdev/kv-store/blob/main/internal/snapshot/snapshot.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_health,node_kvhandlers,node_responses,node_client toneBlue
class node_storeinterface,node_memory toneAmber
class node_wal,node_walrecord,node_snapshot,node_walfile,node_snapshotfile toneMint
class node_server toneRose
```

## Components

### HTTP API

- [Health handler](https://github.com/jusxtdev/kv-store/blob/main/internal/handler/health.go): `internal/handler/health.go`
- [KV handlers](https://github.com/jusxtdev/kv-store/blob/main/internal/handler/kv.go): `internal/handler/kv.go`
- [JSON responses](https://github.com/jusxtdev/kv-store/blob/main/internal/handler/common.go): `internal/handler/common.go`

### Key-Value Storage

- [Store interface](https://github.com/jusxtdev/kv-store/blob/main/internal/repository/interface.go): `internal/repository/interface.go`
- [In-memory store](https://github.com/jusxtdev/kv-store/blob/main/internal/repository/memory.go): `internal/repository/memory.go`

### Durability and Recovery

- [WAL operations](https://github.com/jusxtdev/kv-store/blob/main/internal/wal/wal.go): `internal/wal/wal.go`
- [WAL records](https://github.com/jusxtdev/kv-store/blob/main/internal/wal/record.go): `internal/wal/record.go`
- [Snapshot manager](https://github.com/jusxtdev/kv-store/blob/main/internal/snapshot/snapshot.go): `internal/snapshot/snapshot.go`
- **wal.log**
- **snapshot.json**

### Application Lifecycle

- [API server](https://github.com/jusxtdev/kv-store/blob/main/cmd/api/main.go): `cmd/api/main.go`

### Other components

- **HTTP client**

## Connections

- HTTP client → API server: sends HTTP
- API server → Health handler: routes health
- API server → KV handlers: routes KV
- Health handler → JSON responses: writes JSON
- KV handlers → Store interface: calls operations
- KV handlers → JSON responses: writes JSON
- In-memory store → Store interface: implements
- In-memory store → WAL operations: appends mutations
- WAL operations → WAL records: parses records
- WAL operations → wal.log: appends and replays
- API server → WAL operations: opens and replays
- API server → Snapshot manager: initializes and restores
- API server → In-memory store: restores and enables logging
- Snapshot manager → In-memory store: reads state
- Snapshot manager → WAL operations: reads checkpoint
- Snapshot manager → snapshot.json: writes snapshot
- Snapshot manager → snapshot.json: loads snapshot
- API server → Snapshot manager: triggers every 10 seconds