# omisha123/cdcs architecture

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

- Interactive diagram: https://gitdiagram.com/omisha123/cdcs
- Repository: https://github.com/omisha123/cdcs

## Overview

CDCS is a distributed file-storage and caching system. A client uploads through the HTTP orchestrator, which coordinates Reed–Solomon sharding, shard placement on storage nodes, and metadata persistence and replication; downloads fetch shards and can reconstruct missing data. The graph also preserves the cache, node monitoring/failover, Raft membership/status, and metrics capabilities described in the README. Source excerpts confirm key runtime entry points and storage/cache behavior; some orchestration links are documented only in the README, and unsampled implementation details are not inferred.

Main entry points: [`backend.go`](https://github.com/omisha123/cdcs/blob/main/backend.go) (File orchestrator), [`main.go`](https://github.com/omisha123/cdcs/blob/main/main.go) (HTTP gateway), [`server.go`](https://github.com/omisha123/cdcs/blob/main/server.go) (Storage gRPC service), [`cdcs.go`](https://github.com/omisha123/cdcs/blob/main/cdcs.go) (Cluster RPC client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_gateway["HTTP gateway<br/>[main.go]"]
  node_orchestrator["File orchestrator<br/>[backend.go]"]
end

subgraph group_storage["Shard storage"]
  node_encoding["Reed–Solomon coding<br/>[reedsolomon.go]"]
  node_cluster["Cluster RPC client<br/>[cdcs.go]"]
  node_storage_service["Storage gRPC service<br/>[server.go]"]
  node_cache["2Q cache<br/>[engine_2Q.go]"]
  node_shard_disk[("Shard files<br/>[server.go]")]
  node_storage_nodes["Storage nodes<br/>[node.go]"]
end

subgraph group_metadata["Metadata consensus"]
  node_raft_api["Raft HTTP API<br/>[raftapi.go]"]
  node_raft_cluster["Raft node and FSM<br/>[raft.go]"]
  node_metadata_store[("Persistent metadata<br/>[backend.go]")]
end

subgraph group_operations["Operations and observability"]
  node_monitoring["Metrics and status<br/>[backend.go]"]
  node_node_health["Node health and recovery<br/>[backend.go]"]
end

node_client(("Client"))
node_prometheus(("Prometheus / Grafana"))

node_client -->|"sends requests"| node_gateway
node_gateway -->|"routes uploads"| node_orchestrator
node_gateway -->|"routes downloads"| node_orchestrator
node_orchestrator -->|"encodes and reconstructs"| node_encoding
node_orchestrator -->|"places and fetches shards"| node_cluster
node_cluster -->|"calls shard RPCs"| node_storage_service
node_storage_service -->|"reads and writes"| node_shard_disk
node_storage_service -->|"caches shard data"| node_cache
node_orchestrator -->|"persists file metadata"| node_metadata_store
node_orchestrator -->|"replicates metadata"| node_raft_api
node_raft_api -->|"applies commands"| node_raft_cluster
node_raft_cluster -->|"replicates metadata state"| node_metadata_store
node_orchestrator -->|"detects and reroutes failures"| node_node_health
node_node_health -->|"checks node reachability"| node_cluster
node_gateway -->|"exposes status and metrics"| node_monitoring
node_monitoring -.->|"exports metrics for"| node_prometheus
node_storage_nodes -.->|"hosts shard service"| node_storage_service

click node_gateway "https://github.com/omisha123/cdcs/blob/main/main.go"
click node_orchestrator "https://github.com/omisha123/cdcs/blob/main/backend.go"
click node_encoding "https://github.com/omisha123/cdcs/blob/main/reedsolomon.go"
click node_cluster "https://github.com/omisha123/cdcs/blob/main/cdcs.go"
click node_storage_service "https://github.com/omisha123/cdcs/blob/main/server.go"
click node_cache "https://github.com/omisha123/cdcs/blob/main/engine_2Q.go"
click node_shard_disk "https://github.com/omisha123/cdcs/blob/main/server.go"
click node_storage_nodes "https://github.com/omisha123/cdcs/blob/main/node.go"
click node_raft_api "https://github.com/omisha123/cdcs/blob/main/raftapi.go"
click node_raft_cluster "https://github.com/omisha123/cdcs/blob/main/raft.go"
click node_metadata_store "https://github.com/omisha123/cdcs/blob/main/backend.go"
click node_monitoring "https://github.com/omisha123/cdcs/blob/main/backend.go"
click node_node_health "https://github.com/omisha123/cdcs/blob/main/backend.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_gateway,node_orchestrator,node_client toneBlue
class node_encoding,node_cluster,node_storage_service,node_cache,node_shard_disk,node_storage_nodes toneAmber
class node_raft_api,node_raft_cluster,node_metadata_store toneMint
class node_monitoring,node_node_health toneRose
class node_prometheus toneIndigo
```

## Components

### API and orchestration

- [HTTP gateway](https://github.com/omisha123/cdcs/blob/main/main.go): `main.go`
- [File orchestrator](https://github.com/omisha123/cdcs/blob/main/backend.go): `backend.go`

### Shard storage

- [Reed–Solomon coding](https://github.com/omisha123/cdcs/blob/main/reedsolomon.go): `reedsolomon.go`
- [Cluster RPC client](https://github.com/omisha123/cdcs/blob/main/cdcs.go): `cdcs.go`
- [Storage gRPC service](https://github.com/omisha123/cdcs/blob/main/server.go): `server.go`
- [2Q cache](https://github.com/omisha123/cdcs/blob/main/engine_2Q.go): `engine_2Q.go`
- [Shard files](https://github.com/omisha123/cdcs/blob/main/server.go): `server.go`
- [Storage nodes](https://github.com/omisha123/cdcs/blob/main/node.go): `node.go`

### Metadata consensus

- [Raft HTTP API](https://github.com/omisha123/cdcs/blob/main/raftapi.go): `raftapi.go`
- [Raft node and FSM](https://github.com/omisha123/cdcs/blob/main/raft.go): `raft.go`
- [Persistent metadata](https://github.com/omisha123/cdcs/blob/main/backend.go): `backend.go`

### Operations and observability

- [Metrics and status](https://github.com/omisha123/cdcs/blob/main/backend.go): `backend.go`
- [Node health and recovery](https://github.com/omisha123/cdcs/blob/main/backend.go): `backend.go`

### Other components

- **Client**
- **Prometheus / Grafana**

## Connections

- Client → HTTP gateway: sends requests (evidence: `README.md`)
- HTTP gateway → File orchestrator: routes uploads (evidence: `main.go`)
- HTTP gateway → File orchestrator: routes downloads (evidence: `main.go`)
- File orchestrator → Reed–Solomon coding: encodes and reconstructs (evidence: `README.md`)
- File orchestrator → Cluster RPC client: places and fetches shards (evidence: `README.md`)
- Cluster RPC client → Storage gRPC service: calls shard RPCs (evidence: `cdcs.go`)
- Storage gRPC service → Shard files: reads and writes (evidence: `server.go`)
- Storage gRPC service → 2Q cache: caches shard data (evidence: `server.go`)
- File orchestrator → Persistent metadata: persists file metadata (evidence: `backend.go`)
- File orchestrator → Raft HTTP API: replicates metadata (evidence: `README.md`)
- Raft HTTP API → Raft node and FSM: applies commands (evidence: `raftapi.go`)
- Raft node and FSM → Persistent metadata: replicates metadata state (evidence: `README.md`)
- File orchestrator → Node health and recovery: detects and reroutes failures (evidence: `backend.go`)
- Node health and recovery → Cluster RPC client: checks node reachability (evidence: `backend.go`)
- HTTP gateway → Metrics and status: exposes status and metrics (evidence: `main.go`)
- Metrics and status → Prometheus / Grafana: exports metrics for (evidence: `README.md`)
- Storage nodes → Storage gRPC service: hosts shard service (evidence: `README.md`)
