# alsotoes/momo architecture

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

- Interactive diagram: https://gitdiagram.com/alsotoes/momo
- Repository: https://github.com/alsotoes/momo

## Overview

Momo is a distributed, content-addressed object store. A client selects a daemon, hashes and optionally encrypts content, then sends it over the native protocol; the server stores the blob and coordinates configured replication. Users can also access objects through the S3-compatible gateway or the FUSE filesystem. The architecture includes pluggable blob backends, cluster placement and coordination, integrity/durability mechanisms, and optional distributed metadata and OPRF. Relationships for unsampled subsystems are shown only where the README documents them; some implementation details are therefore omitted.

Main entry points: [`src/server/server.go`](https://github.com/alsotoes/momo/blob/master/src/server/server.go) (Server daemon), [`src/storage/storage.go`](https://github.com/alsotoes/momo/blob/master/src/storage/storage.go) (CAS store), [`src/client/client.go`](https://github.com/alsotoes/momo/blob/master/src/client/client.go) (Native client), [`src/momo.go`](https://github.com/alsotoes/momo/blob/master/src/momo.go) (Momo runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Access surfaces"]
  node_momo["Momo runner<br/>[momo.go]"]
  node_client["Native client<br/>[client.go]"]
end

subgraph group_cluster["Cluster services"]
  node_daemon["Server daemon<br/>[server.go]"]
  node_replication["Replication strategies<br/>[replication.go]"]
  node_p2p["P2P coordination<br/>[gossip.go]"]
  node_metadata_rpc["Distributed metadata<br/>[metadata_rpc.go]"]
  node_query["Cluster queries<br/>[query_handler.go]"]
  node_placement["CRUSH placement<br/>[crush.go]"]
  node_metrics["Prometheus metrics<br/>[metrics.go]"]
end

subgraph group_store["Storage and durability"]
  node_cas[("CAS store<br/>[storage.go]")]
  node_blob_backends["Blob backends<br/>[factory.go]"]
  node_integrity["Integrity verification<br/>[integrity.go]"]
  node_durability["Write durability<br/>[durability.go]"]
  node_rebuild["Rebuild<br/>[rebuild.go]"]
end

subgraph group_protocol["Protocols and security"]
  node_native_transport["TCP / QUIC<br/>[momo_tcp.go]"]
  node_s3_gateway["S3 gateway<br/>[s3_communicator.go]"]
  node_crypto["Client encryption / OPRF<br/>[envelope.go]"]
  node_oprf_service["OPRF service<br/>[oprf_service.go]"]
end

subgraph group_fs["Filesystem access"]
  node_fuse_adapter["FUSE adapter<br/>[fuse.go]"]
  node_momofs["POSIX namespace<br/>[momofs.go]"]
end

node_operator(("Operator / user"))
node_s3_user(("S3 client"))
node_posix_user(("POSIX user"))

node_operator -->|"runs"| node_momo
node_momo -->|"starts client"| node_client
node_client -->|"sends objects"| node_native_transport
node_native_transport -->|"serves requests"| node_daemon
node_daemon -->|"stores objects"| node_cas
node_cas -->|"stores blob bytes"| node_blob_backends
node_daemon -->|"replicates writes"| node_replication
node_replication -->|"forwards data"| node_native_transport
node_client -->|"chooses replicas"| node_placement
node_daemon -->|"starts membership"| node_p2p
node_daemon -->|"handles queries"| node_query
node_query -->|"reads metadata"| node_cas
node_p2p -.->|"coordinates metadata"| node_metadata_rpc
node_metadata_rpc -->|"reads and writes"| node_cas
node_cas -.->|"verifies content"| node_integrity
node_cas -.->|"applies barrier"| node_durability
node_daemon -.->|"rebuilds replicas"| node_rebuild
node_s3_user -->|"requests objects"| node_s3_gateway
node_s3_gateway -->|"serves gateway"| node_daemon
node_client -->|"encrypts content"| node_crypto
node_daemon -->|"evaluates shares"| node_oprf_service
node_client -.->|"reports activity"| node_metrics
node_operator -->|"starts server"| node_momo
node_posix_user -->|"uses filesystem"| node_fuse_adapter
node_momo -->|"starts FUSE"| node_fuse_adapter
node_fuse_adapter -->|"adapts operations"| node_momofs
node_momofs -->|"stores namespace data"| node_cas

click node_momo "https://github.com/alsotoes/momo/blob/master/src/momo.go"
click node_client "https://github.com/alsotoes/momo/blob/master/src/client/client.go"
click node_daemon "https://github.com/alsotoes/momo/blob/master/src/server/server.go"
click node_replication "https://github.com/alsotoes/momo/blob/master/src/server/replication.go"
click node_p2p "https://github.com/alsotoes/momo/blob/master/src/p2p/gossip.go"
click node_metadata_rpc "https://github.com/alsotoes/momo/blob/master/src/p2p/metadata_rpc.go"
click node_query "https://github.com/alsotoes/momo/blob/master/src/server/query_handler.go"
click node_placement "https://github.com/alsotoes/momo/blob/master/src/common/crush.go"
click node_cas "https://github.com/alsotoes/momo/blob/master/src/storage/storage.go"
click node_blob_backends "https://github.com/alsotoes/momo/blob/master/src/storage/factory.go"
click node_integrity "https://github.com/alsotoes/momo/blob/master/src/storage/integrity.go"
click node_durability "https://github.com/alsotoes/momo/blob/master/src/storage/durability.go"
click node_rebuild "https://github.com/alsotoes/momo/blob/master/src/storage/rebuild.go"
click node_native_transport "https://github.com/alsotoes/momo/blob/master/src/transport/momo_tcp.go"
click node_s3_gateway "https://github.com/alsotoes/momo/blob/master/src/transport/s3_communicator.go"
click node_crypto "https://github.com/alsotoes/momo/blob/master/src/crypto/envelope.go"
click node_oprf_service "https://github.com/alsotoes/momo/blob/master/src/server/oprf_service.go"
click node_metrics "https://github.com/alsotoes/momo/blob/master/src/metrics/metrics.go"
click node_fuse_adapter "https://github.com/alsotoes/momo/blob/master/src/momofs/fuse.go"
click node_momofs "https://github.com/alsotoes/momo/blob/master/src/momofs/momofs.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_momo,node_client,node_operator,node_s3_user,node_posix_user toneBlue
class node_daemon,node_replication,node_p2p,node_metadata_rpc,node_query,node_placement,node_metrics toneAmber
class node_cas,node_blob_backends,node_integrity,node_durability,node_rebuild toneMint
class node_native_transport,node_s3_gateway,node_crypto,node_oprf_service toneRose
class node_fuse_adapter,node_momofs toneIndigo
```

## Components

### Access surfaces

- [Momo runner](https://github.com/alsotoes/momo/blob/master/src/momo.go): `src/momo.go`
- [Native client](https://github.com/alsotoes/momo/blob/master/src/client/client.go): `src/client/client.go`

### Cluster services

- [Server daemon](https://github.com/alsotoes/momo/blob/master/src/server/server.go): `src/server/server.go`
- [Replication strategies](https://github.com/alsotoes/momo/blob/master/src/server/replication.go): `src/server/replication.go`
- [P2P coordination](https://github.com/alsotoes/momo/blob/master/src/p2p/gossip.go): `src/p2p/gossip.go`
- [Distributed metadata](https://github.com/alsotoes/momo/blob/master/src/p2p/metadata_rpc.go): `src/p2p/metadata_rpc.go`
- [Cluster queries](https://github.com/alsotoes/momo/blob/master/src/server/query_handler.go): `src/server/query_handler.go`
- [CRUSH placement](https://github.com/alsotoes/momo/blob/master/src/common/crush.go): `src/common/crush.go`
- [Prometheus metrics](https://github.com/alsotoes/momo/blob/master/src/metrics/metrics.go): `src/metrics/metrics.go`

### Storage and durability

- [CAS store](https://github.com/alsotoes/momo/blob/master/src/storage/storage.go): `src/storage/storage.go`
- [Blob backends](https://github.com/alsotoes/momo/blob/master/src/storage/factory.go): `src/storage/factory.go`
- [Integrity verification](https://github.com/alsotoes/momo/blob/master/src/storage/integrity.go): `src/storage/integrity.go`
- [Write durability](https://github.com/alsotoes/momo/blob/master/src/storage/durability.go): `src/storage/durability.go`
- [Rebuild](https://github.com/alsotoes/momo/blob/master/src/storage/rebuild.go): `src/storage/rebuild.go`

### Protocols and security

- [TCP / QUIC](https://github.com/alsotoes/momo/blob/master/src/transport/momo_tcp.go): `src/transport/momo_tcp.go`
- [S3 gateway](https://github.com/alsotoes/momo/blob/master/src/transport/s3_communicator.go): `src/transport/s3_communicator.go`
- [Client encryption / OPRF](https://github.com/alsotoes/momo/blob/master/src/crypto/envelope.go): `src/crypto/envelope.go`
- [OPRF service](https://github.com/alsotoes/momo/blob/master/src/server/oprf_service.go): `src/server/oprf_service.go`

### Filesystem access

- [FUSE adapter](https://github.com/alsotoes/momo/blob/master/src/momofs/fuse.go): `src/momofs/fuse.go`
- [POSIX namespace](https://github.com/alsotoes/momo/blob/master/src/momofs/momofs.go): `src/momofs/momofs.go`

### Other components

- **Operator / user**
- **S3 client**
- **POSIX user**

## Connections

- Operator / user → Momo runner: runs
- Momo runner → Native client: starts client (evidence: `src/momo.go`)
- Native client → TCP / QUIC: sends objects (evidence: `src/client/client.go`)
- TCP / QUIC → Server daemon: serves requests
- Server daemon → CAS store: stores objects (evidence: `src/server/server.go`)
- CAS store → Blob backends: stores blob bytes (evidence: `src/storage/storage.go`)
- Server daemon → Replication strategies: replicates writes
- Replication strategies → TCP / QUIC: forwards data
- Native client → CRUSH placement: chooses replicas
- Server daemon → P2P coordination: starts membership (evidence: `src/server/server.go`)
- Server daemon → Cluster queries: handles queries (evidence: `src/server/query_handler.go`)
- Cluster queries → CAS store: reads metadata (evidence: `src/server/query_handler.go`)
- P2P coordination → Distributed metadata: coordinates metadata
- Distributed metadata → CAS store: reads and writes (evidence: `src/p2p/metadata_rpc.go`)
- CAS store → Integrity verification: verifies content
- CAS store → Write durability: applies barrier
- Server daemon → Rebuild: rebuilds replicas
- S3 client → S3 gateway: requests objects
- S3 gateway → Server daemon: serves gateway
- Native client → Client encryption / OPRF: encrypts content (evidence: `src/client/client.go`)
- Server daemon → OPRF service: evaluates shares (evidence: `src/server/oprf_service.go`)
- Native client → Prometheus metrics: reports activity
- Operator / user → Momo runner: starts server (evidence: `src/momo.go`)
- POSIX user → FUSE adapter: uses filesystem
- Momo runner → FUSE adapter: starts FUSE
- FUSE adapter → POSIX namespace: adapts operations (evidence: `src/momofs/fuse.go`)
- POSIX namespace → CAS store: stores namespace data (evidence: `src/momofs/momofs.go`)
