# kalbasit/ncps architecture

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

- Interactive diagram: https://gitdiagram.com/kalbasit/ncps
- Repository: https://github.com/kalbasit/ncps
- Video tour (about a minute): https://gitdiagram.com/kalbasit/ncps/video

## Overview

ncps is a Nix binary-cache proxy: Nix clients request metadata and store files, which the server serves from local cache or retrieves from configured upstream caches and retains for reuse. The README documents multiple upstreams, local/S3 storage, database choices, chunked CDC, signing, Redis-backed high availability, and observability. The graph reflects those documented capabilities and the sampled HTTP, application-entry, and database code; internal cache-to-backend wiring is not fully visible in the excerpts.

Main entry points: [`pkg/cache/cache.go`](https://github.com/kalbasit/ncps/blob/main/pkg/cache/cache.go) (Cache coordinator), [`pkg/server/server.go`](https://github.com/kalbasit/ncps/blob/main/pkg/server/server.go) (HTTP API), [`pkg/ncps/root.go`](https://github.com/kalbasit/ncps/blob/main/pkg/ncps/root.go) (CLI application), [`pkg/ncps/serve.go`](https://github.com/kalbasit/ncps/blob/main/pkg/ncps/serve.go) (Serve command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application"]
  node_main["Process entry<br/>[main.go]"]
  node_app["CLI application<br/>[root.go]"]
  node_serve_cmd["Serve command<br/>[serve.go]"]
end

subgraph group_http["Cache API"]
  node_http_server["HTTP API<br/>[server.go]"]
end

subgraph group_cache["Cache processing"]
  node_cache_core["Cache coordinator<br/>[cache.go]"]
  node_upstreams["Upstream caches<br/>[cache.go]"]
  node_nar_processing["NAR processing<br/>[reader.go]"]
  node_chunking["Chunking<br/>[chunker.go]"]
  node_cache_policy["Cache policy<br/>[queries.go]"]
  node_signing["NAR metadata<br/>[hash.go]"]
end

subgraph group_persistence["Persistence"]
  node_database_client["Database client<br/>[client.go]"]
  node_database_store[("Cache database<br/>[narinfo.go]")]
  node_storage["Storage interface<br/>[store.go]"]
  node_local_storage["Local storage<br/>[local.go]"]
  node_s3_storage["S3 storage<br/>[s3.go]"]
  node_redis_lock["Redis locking<br/>[locker.go]"]
end

subgraph group_operations["Operations"]
  node_migrate_cmd["Migration commands<br/>[migrate.go]"]
  node_fsck["Cache verification<br/>[fsck.go]"]
  node_telemetry["Metrics and tracing<br/>[otel.go]"]
end

node_nix_client(("Nix client"))
node_upstream_service["Upstream cache"]
node_local_files[("Local filesystem")]
node_s3_service[("S3-compatible store")]
node_redis_service[("Redis")]

node_nix_client -->|"HTTP requests"| node_http_server
node_main -->|"starts"| node_app
node_app -->|"dispatches"| node_serve_cmd
node_serve_cmd -->|"starts server"| node_http_server
node_http_server -->|"handles cache requests"| node_cache_core
node_cache_core -->|"fetches misses"| node_upstreams
node_upstreams -->|"requests NARs"| node_upstream_service
node_cache_core -->|"reads and writes metadata"| node_database_client
node_database_client -->|"queries and persists"| node_database_store
node_cache_core -->|"stores and reads NARs"| node_storage
node_storage -->|"selects backend"| node_local_storage
node_storage -->|"selects backend"| node_s3_storage
node_local_storage -->|"reads and writes"| node_local_files
node_s3_storage -->|"reads and writes"| node_s3_service
node_cache_core -->|"processes NARs"| node_nar_processing
node_cache_core -.->|"chunks content"| node_chunking
node_cache_core -->|"applies cache policy"| node_cache_policy
node_http_server -->|"serves cache metadata"| node_signing
node_serve_cmd -.->|"configures distributed locking"| node_redis_lock
node_redis_lock -.->|"acquires locks"| node_redis_service
node_app -->|"dispatches migrations"| node_migrate_cmd
node_app -->|"dispatches verification"| node_fsck
node_http_server -->|"records telemetry"| node_telemetry

click node_main "https://github.com/kalbasit/ncps/blob/main/main.go"
click node_app "https://github.com/kalbasit/ncps/blob/main/pkg/ncps/root.go"
click node_serve_cmd "https://github.com/kalbasit/ncps/blob/main/pkg/ncps/serve.go"
click node_http_server "https://github.com/kalbasit/ncps/blob/main/pkg/server/server.go"
click node_cache_core "https://github.com/kalbasit/ncps/blob/main/pkg/cache/cache.go"
click node_upstreams "https://github.com/kalbasit/ncps/blob/main/pkg/cache/upstream/cache.go"
click node_nar_processing "https://github.com/kalbasit/ncps/blob/main/pkg/nar/reader.go"
click node_chunking "https://github.com/kalbasit/ncps/blob/main/pkg/chunker/chunker.go"
click node_cache_policy "https://github.com/kalbasit/ncps/blob/main/pkg/cache/queries.go"
click node_signing "https://github.com/kalbasit/ncps/blob/main/pkg/narinfo/hash.go"
click node_database_client "https://github.com/kalbasit/ncps/blob/main/pkg/database/client.go"
click node_database_store "https://github.com/kalbasit/ncps/blob/main/ent/schema/narinfo.go"
click node_storage "https://github.com/kalbasit/ncps/blob/main/pkg/storage/store.go"
click node_local_storage "https://github.com/kalbasit/ncps/blob/main/pkg/storage/local/local.go"
click node_s3_storage "https://github.com/kalbasit/ncps/blob/main/pkg/storage/s3/s3.go"
click node_redis_lock "https://github.com/kalbasit/ncps/blob/main/pkg/lock/redis/locker.go"
click node_migrate_cmd "https://github.com/kalbasit/ncps/blob/main/pkg/ncps/migrate.go"
click node_fsck "https://github.com/kalbasit/ncps/blob/main/pkg/ncps/fsck.go"
click node_telemetry "https://github.com/kalbasit/ncps/blob/main/pkg/otel/otel.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_main,node_app,node_serve_cmd,node_nix_client toneBlue
class node_http_server,node_upstream_service,node_local_files,node_s3_service,node_redis_service toneAmber
class node_cache_core,node_upstreams,node_nar_processing,node_chunking,node_cache_policy,node_signing toneMint
class node_database_client,node_database_store,node_storage,node_local_storage,node_s3_storage,node_redis_lock toneRose
class node_migrate_cmd,node_fsck,node_telemetry toneIndigo
```

## Components

### Application

- [Process entry](https://github.com/kalbasit/ncps/blob/main/main.go): `main.go`
- [CLI application](https://github.com/kalbasit/ncps/blob/main/pkg/ncps/root.go): `pkg/ncps/root.go`
- [Serve command](https://github.com/kalbasit/ncps/blob/main/pkg/ncps/serve.go): `pkg/ncps/serve.go`

### Cache API

- [HTTP API](https://github.com/kalbasit/ncps/blob/main/pkg/server/server.go): `pkg/server/server.go`

### Cache processing

- [Cache coordinator](https://github.com/kalbasit/ncps/blob/main/pkg/cache/cache.go): `pkg/cache/cache.go`
- [Upstream caches](https://github.com/kalbasit/ncps/blob/main/pkg/cache/upstream/cache.go): `pkg/cache/upstream/cache.go`
- [NAR processing](https://github.com/kalbasit/ncps/blob/main/pkg/nar/reader.go): `pkg/nar/reader.go`
- [Chunking](https://github.com/kalbasit/ncps/blob/main/pkg/chunker/chunker.go): `pkg/chunker/chunker.go`
- [Cache policy](https://github.com/kalbasit/ncps/blob/main/pkg/cache/queries.go): `pkg/cache/queries.go`
- [NAR metadata](https://github.com/kalbasit/ncps/blob/main/pkg/narinfo/hash.go): `pkg/narinfo/hash.go`

### Persistence

- [Database client](https://github.com/kalbasit/ncps/blob/main/pkg/database/client.go): `pkg/database/client.go`
- [Cache database](https://github.com/kalbasit/ncps/blob/main/ent/schema/narinfo.go): `ent/schema/narinfo.go`
- [Storage interface](https://github.com/kalbasit/ncps/blob/main/pkg/storage/store.go): `pkg/storage/store.go`
- [Local storage](https://github.com/kalbasit/ncps/blob/main/pkg/storage/local/local.go): `pkg/storage/local/local.go`
- [S3 storage](https://github.com/kalbasit/ncps/blob/main/pkg/storage/s3/s3.go): `pkg/storage/s3/s3.go`
- [Redis locking](https://github.com/kalbasit/ncps/blob/main/pkg/lock/redis/locker.go): `pkg/lock/redis/locker.go`

### Operations

- [Migration commands](https://github.com/kalbasit/ncps/blob/main/pkg/ncps/migrate.go): `pkg/ncps/migrate.go`
- [Cache verification](https://github.com/kalbasit/ncps/blob/main/pkg/ncps/fsck.go): `pkg/ncps/fsck.go`
- [Metrics and tracing](https://github.com/kalbasit/ncps/blob/main/pkg/otel/otel.go): `pkg/otel/otel.go`

### Other components

- **Nix client**
- **Upstream cache**
- **Local filesystem**
- **S3-compatible store**
- **Redis**

## Connections

- Nix client → HTTP API: HTTP requests
- Process entry → CLI application: starts
- CLI application → Serve command: dispatches
- Serve command → HTTP API: starts server
- HTTP API → Cache coordinator: handles cache requests
- Cache coordinator → Upstream caches: fetches misses
- Upstream caches → Upstream cache: requests NARs
- Cache coordinator → Database client: reads and writes metadata
- Database client → Cache database: queries and persists
- Cache coordinator → Storage interface: stores and reads NARs
- Storage interface → Local storage: selects backend
- Storage interface → S3 storage: selects backend
- Local storage → Local filesystem: reads and writes
- S3 storage → S3-compatible store: reads and writes
- Cache coordinator → NAR processing: processes NARs
- Cache coordinator → Chunking: chunks content
- Cache coordinator → Cache policy: applies cache policy
- HTTP API → NAR metadata: serves cache metadata
- Serve command → Redis locking: configures distributed locking
- Redis locking → Redis: acquires locks
- CLI application → Migration commands: dispatches migrations
- CLI application → Cache verification: dispatches verification
- HTTP API → Metrics and tracing: records telemetry