# imdigitalashish/rubicon-poc architecture

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

- Interactive diagram: https://gitdiagram.com/imdigitalashish/rubicon-poc
- Repository: https://github.com/imdigitalashish/rubicon-poc

## Overview

rubicon-poc is a runnable, single-process proof of concept for GitHub’s Rubicon-style Git storage architecture. Its principal workflow creates Git objects and packs, routes pushes and fetches through Spokes to disposable replica caches, stores durable packs in Blob Storage, and commits ref and manifest changes through Ref-CAS. Background compaction leases shards, merges and verifies packs, publishes replacements, and retires old packs. The README documents these capabilities; unsampled modules are represented only where that documentation supports them.

Main entry points: [`src/cluster.rs`](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/cluster.rs) (Cluster assembly), [`src/spokes.rs`](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/spokes.rs) (Spokes routing), [`src/refcas.rs`](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/refcas.rs) (Ref-CAS transactions), [`src/replica.rs`](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/replica.rs) (Replica push)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client workflow"]
  node_cli["Demo and bench<br/>[main.rs]"]
  node_agent["Agent changes<br/>[agent.rs]"]
  node_objects["Git objects and packs<br/>[object.rs]"]
end

subgraph group_serving["Replica serving"]
  node_spokes["Spokes routing<br/>[spokes.rs]"]
  node_replica_push["Replica push<br/>[replica.rs]"]
  node_replica_fetch["Replica fetch and cache<br/>[replica.rs]"]
end

subgraph group_storage["Durable storage"]
  node_blob[("Blob Storage<br/>[blob.rs]")]
  node_refcas["Ref-CAS transactions<br/>[refcas.rs]"]
  node_log_nodes[("Quorum log nodes<br/>[refcas.rs]")]
end

subgraph group_maintenance["Background maintenance"]
  node_compactor["Compaction workers<br/>[compaction.rs]"]
end

subgraph group_runtime["Runtime wiring"]
  node_cluster["Cluster assembly<br/>[cluster.rs]"]
end

node_git_client(("Git client"))

node_git_client -->|"pushes and fetches"| node_spokes
node_cli -->|"creates cluster"| node_cluster
node_cli -->|"creates changes"| node_agent
node_cli -->|"runs requests"| node_spokes
node_agent -->|"encodes pack"| node_objects
node_spokes -->|"routes push"| node_replica_push
node_spokes -->|"routes fetch"| node_replica_fetch
node_replica_push -->|"indexes pack"| node_objects
node_replica_push -->|"uploads pack"| node_blob
node_replica_push -->|"commits refs"| node_refcas
node_replica_fetch -->|"checks version"| node_refcas
node_replica_fetch -->|"pulls packs"| node_blob
node_replica_fetch -->|"opens packs"| node_objects
node_refcas -->|"replicates appends"| node_log_nodes
node_compactor -->|"leases and merges packs"| node_blob
node_compactor -->|"publishes and retires"| node_refcas
node_cluster -->|"constructs store"| node_blob
node_cluster -->|"constructs log"| node_refcas
node_cluster -->|"assembles replicas"| node_spokes
node_cluster -->|"starts workers"| node_compactor

click node_cli "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/main.rs"
click node_agent "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/agent.rs"
click node_objects "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/object.rs"
click node_spokes "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/spokes.rs"
click node_replica_push "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/replica.rs"
click node_replica_fetch "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/replica.rs"
click node_blob "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/blob.rs"
click node_refcas "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/refcas.rs"
click node_log_nodes "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/refcas.rs"
click node_compactor "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/compaction.rs"
click node_cluster "https://github.com/imdigitalashish/rubicon-poc/blob/main/src/cluster.rs"

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_cli,node_agent,node_objects,node_git_client toneBlue
class node_spokes,node_replica_push,node_replica_fetch toneAmber
class node_blob,node_refcas,node_log_nodes toneMint
class node_compactor toneRose
class node_cluster toneIndigo
```

## Components

### Client workflow

- [Demo and bench](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/main.rs): `src/main.rs`
- [Agent changes](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/agent.rs): `src/agent.rs`
- [Git objects and packs](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/object.rs): `src/object.rs`

### Replica serving

- [Spokes routing](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/spokes.rs): `src/spokes.rs`
- [Replica push](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/replica.rs): `src/replica.rs`
- [Replica fetch and cache](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/replica.rs): `src/replica.rs`

### Durable storage

- [Blob Storage](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/blob.rs): `src/blob.rs`
- [Ref-CAS transactions](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/refcas.rs): `src/refcas.rs`
- [Quorum log nodes](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/refcas.rs): `src/refcas.rs`

### Background maintenance

- [Compaction workers](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/compaction.rs): `src/compaction.rs`

### Runtime wiring

- [Cluster assembly](https://github.com/imdigitalashish/rubicon-poc/blob/main/src/cluster.rs): `src/cluster.rs`

### Other components

- **Git client**

## Connections

- Git client → Spokes routing: pushes and fetches (evidence: `README.md`)
- Demo and bench → Cluster assembly: creates cluster (evidence: `src/main.rs`)
- Demo and bench → Agent changes: creates changes (evidence: `src/main.rs`)
- Demo and bench → Spokes routing: runs requests (evidence: `src/main.rs`)
- Agent changes → Git objects and packs: encodes pack (evidence: `src/agent.rs`)
- Spokes routing → Replica push: routes push (evidence: `src/spokes.rs`)
- Spokes routing → Replica fetch and cache: routes fetch (evidence: `src/spokes.rs`)
- Replica push → Git objects and packs: indexes pack (evidence: `src/replica.rs`)
- Replica push → Blob Storage: uploads pack (evidence: `src/replica.rs`)
- Replica push → Ref-CAS transactions: commits refs (evidence: `src/replica.rs`)
- Replica fetch and cache → Ref-CAS transactions: checks version (evidence: `README.md`)
- Replica fetch and cache → Blob Storage: pulls packs (evidence: `src/replica.rs`)
- Replica fetch and cache → Git objects and packs: opens packs (evidence: `src/replica.rs`)
- Ref-CAS transactions → Quorum log nodes: replicates appends (evidence: `src/refcas.rs`)
- Compaction workers → Blob Storage: leases and merges packs (evidence: `src/compaction.rs`)
- Compaction workers → Ref-CAS transactions: publishes and retires (evidence: `src/compaction.rs`)
- Cluster assembly → Blob Storage: constructs store (evidence: `src/cluster.rs`)
- Cluster assembly → Ref-CAS transactions: constructs log (evidence: `src/cluster.rs`)
- Cluster assembly → Spokes routing: assembles replicas (evidence: `src/cluster.rs`)
- Cluster assembly → Compaction workers: starts workers (evidence: `src/cluster.rs`)
