# 0neshot101/ferrum architecture

> Architecture diagram of the GitHub repository 0neshot101/ferrum, 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/0neshot101/ferrum
- Repository: https://github.com/0neshot101/ferrum

## Overview

Ferrum is a multi-format package gateway: clients use ordinary package-manager URLs, while the service authenticates repository metadata, fetches and verifies package bodies on demand, and serves them from bounded local storage backed by private S3-compatible storage. The main runtime path is configured and assembled at startup, then public requests pass through the HTTP server and shared-fill fetch path. Separate branches cover suite synchronization and publication, recovery, administration, and the dashboard. Edges use the README and source-index references; unsampled integration details are left unverified.

Main entry points: [`crates/ferrum/src/admin/routes.rs`](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/admin/routes.rs) (Admin routes), [`crates/ferrum/src/app.rs`](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/app.rs) (Startup wiring), [`crates/ferrum/src/sync.rs`](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/sync.rs) (Suite synchronization), [`crates/ferrum/src/server.rs`](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/server.rs) (Public HTTP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway runtime"]
  node_app["Startup wiring<br/>[app.rs]"]
  node_config["Runtime config<br/>[config.rs]"]
  node_server["Public HTTP<br/>[server.rs]"]
  node_fetch["Shared package fills<br/>[fetch.rs]"]
end

subgraph group_trust["Repository trust"]
  node_sync["Suite synchronization<br/>[sync.rs]"]
  node_formats["Metadata parsers<br/>[index.rs]"]
  node_verifier["Signature verifier<br/>[main.rs]"]
end

subgraph group_storage["Storage and recovery"]
  node_storagecore["Capture and budgets<br/>[capture.rs]"]
  node_catalog[("SQLite catalog<br/>[catalog.rs]")]
  node_disk[("Local object spool<br/>[disk.rs]")]
  node_s3["S3 transport<br/>[production.rs]"]
  node_recovery["Generation recovery<br/>[recovery.rs]"]
end

subgraph group_admin["Operations and admin"]
  node_health["Health and metrics<br/>[health.rs]"]
  node_adminroutes["Admin routes<br/>[routes.rs]"]
  node_jobs["Operation jobs<br/>[jobs.rs]"]
  node_prewarm["Package prewarming<br/>[prewarm.rs]"]
end

subgraph group_ui["Admin dashboard"]
  node_storagepage["Storage dashboard<br/>[StoragePage.svelte]"]
  node_adminapi["Dashboard API client<br/>[api.ts]"]
end

node_client(("Package client"))
node_operator(("Operator"))
node_upstream["Repository origin"]
node_s3service["S3 service"]
node_browser(("Admin user"))

node_client -->|"requests packages"| node_server
node_app -->|"loads settings"| node_config
node_app -->|"wires listener"| node_server
node_app -->|"wires fills"| node_fetch
node_app -->|"wires synchronizer"| node_sync
node_app -->|"wires health"| node_health
node_server -->|"requests fills"| node_fetch
node_server -.->|"records metrics"| node_health
node_fetch -.->|"fetches bodies"| node_upstream
node_sync -->|"fetches metadata"| node_upstream
node_sync -->|"parses indexes"| node_formats
node_formats -.->|"authenticates metadata"| node_verifier
node_sync -.->|"publishes view"| node_catalog
node_storagecore -->|"records captures"| node_catalog
node_storagecore -->|"stages objects"| node_disk
node_storagecore -->|"stores captures"| node_s3
node_s3 -.->|"transfers objects"| node_s3service
node_recovery -->|"reads publication state"| node_catalog
node_recovery -->|"recovers generations"| node_s3
node_recovery -->|"verifies proofs"| node_verifier
node_health -->|"mounts admin routes"| node_adminroutes
node_adminroutes -->|"routes job requests"| node_jobs
node_adminroutes -->|"serves telemetry"| node_health
node_operator -->|"manages gateway"| node_adminroutes
node_adminroutes -->|"routes prewarm"| node_prewarm
node_browser -->|"views storage"| node_storagepage
node_storagepage -->|"calls storage API"| node_adminapi
node_adminapi -.->|"sends admin requests"| node_adminroutes

click node_app "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/app.rs"
click node_config "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/config.rs"
click node_server "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/server.rs"
click node_fetch "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/fetch.rs"
click node_sync "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/sync.rs"
click node_formats "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-apt/src/index.rs"
click node_verifier "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-verifier/src/main.rs"
click node_storagecore "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/capture.rs"
click node_catalog "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/catalog.rs"
click node_disk "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/disk.rs"
click node_s3 "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/s3/production.rs"
click node_recovery "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/recovery.rs"
click node_health "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/health.rs"
click node_adminroutes "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/admin/routes.rs"
click node_jobs "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/admin/jobs.rs"
click node_prewarm "https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/prewarm.rs"
click node_storagepage "https://github.com/0neshot101/ferrum/blob/main/ui/src/lib/components/StoragePage.svelte"
click node_adminapi "https://github.com/0neshot101/ferrum/blob/main/ui/src/lib/services/api.ts"

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_app,node_config,node_server,node_fetch,node_client,node_browser toneBlue
class node_sync,node_formats,node_verifier toneAmber
class node_storagecore,node_catalog,node_disk,node_s3,node_recovery toneMint
class node_health,node_adminroutes,node_jobs,node_prewarm toneRose
class node_storagepage,node_adminapi,node_operator,node_upstream,node_s3service toneIndigo
```

## Components

### Gateway runtime

- [Startup wiring](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/app.rs): `crates/ferrum/src/app.rs`
- [Runtime config](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/config.rs): `crates/ferrum/src/config.rs`
- [Public HTTP](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/server.rs): `crates/ferrum/src/server.rs`
- [Shared package fills](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/fetch.rs): `crates/ferrum/src/fetch.rs`

### Repository trust

- [Suite synchronization](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/sync.rs): `crates/ferrum/src/sync.rs`
- [Metadata parsers](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-apt/src/index.rs): `crates/ferrum-apt/src/index.rs`
- [Signature verifier](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-verifier/src/main.rs): `crates/ferrum-verifier/src/main.rs`

### Storage and recovery

- [Capture and budgets](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/capture.rs): `crates/ferrum-storage/src/capture.rs`
- [SQLite catalog](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/catalog.rs): `crates/ferrum-storage/src/catalog.rs`
- [Local object spool](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/disk.rs): `crates/ferrum-storage/src/disk.rs`
- [S3 transport](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/s3/production.rs): `crates/ferrum-storage/src/s3/production.rs`
- [Generation recovery](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum-storage/src/recovery.rs): `crates/ferrum-storage/src/recovery.rs`

### Operations and admin

- [Health and metrics](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/health.rs): `crates/ferrum/src/health.rs`
- [Admin routes](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/admin/routes.rs): `crates/ferrum/src/admin/routes.rs`
- [Operation jobs](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/admin/jobs.rs): `crates/ferrum/src/admin/jobs.rs`
- [Package prewarming](https://github.com/0neshot101/ferrum/blob/main/crates/ferrum/src/prewarm.rs): `crates/ferrum/src/prewarm.rs`

### Admin dashboard

- [Storage dashboard](https://github.com/0neshot101/ferrum/blob/main/ui/src/lib/components/StoragePage.svelte): `ui/src/lib/components/StoragePage.svelte`
- [Dashboard API client](https://github.com/0neshot101/ferrum/blob/main/ui/src/lib/services/api.ts): `ui/src/lib/services/api.ts`

### Other components

- **Package client**
- **Operator**
- **Repository origin**
- **S3 service**
- **Admin user**

## Connections

- Package client → Public HTTP: requests packages (evidence: `README.md`)
- Startup wiring → Runtime config: loads settings (evidence: `crates/ferrum/src/app.rs`)
- Startup wiring → Public HTTP: wires listener (evidence: `crates/ferrum/src/app.rs`)
- Startup wiring → Shared package fills: wires fills (evidence: `crates/ferrum/src/app.rs`)
- Startup wiring → Suite synchronization: wires synchronizer (evidence: `crates/ferrum/src/app.rs`)
- Startup wiring → Health and metrics: wires health (evidence: `crates/ferrum/src/app.rs`)
- Public HTTP → Shared package fills: requests fills (evidence: `crates/ferrum/src/server.rs`)
- Public HTTP → Health and metrics: records metrics (evidence: `crates/ferrum/src/server.rs`)
- Shared package fills → Repository origin: fetches bodies
- Suite synchronization → Repository origin: fetches metadata (evidence: `crates/ferrum/src/sync.rs`)
- Suite synchronization → Metadata parsers: parses indexes (evidence: `crates/ferrum/src/sync.rs`)
- Metadata parsers → Signature verifier: authenticates metadata
- Suite synchronization → SQLite catalog: publishes view
- Capture and budgets → SQLite catalog: records captures (evidence: `crates/ferrum-storage/src/capture.rs`)
- Capture and budgets → Local object spool: stages objects (evidence: `crates/ferrum-storage/src/capture.rs`)
- Capture and budgets → S3 transport: stores captures (evidence: `crates/ferrum-storage/src/capture.rs`)
- S3 transport → S3 service: transfers objects
- Generation recovery → SQLite catalog: reads publication state (evidence: `crates/ferrum-storage/src/recovery.rs`)
- Generation recovery → S3 transport: recovers generations (evidence: `crates/ferrum-storage/src/recovery.rs`)
- Generation recovery → Signature verifier: verifies proofs (evidence: `crates/ferrum-storage/src/recovery.rs`)
- Health and metrics → Admin routes: mounts admin routes (evidence: `crates/ferrum/src/health.rs`)
- Admin routes → Operation jobs: routes job requests (evidence: `crates/ferrum/src/admin/routes.rs`)
- Admin routes → Health and metrics: serves telemetry (evidence: `crates/ferrum/src/admin/routes.rs`)
- Operator → Admin routes: manages gateway (evidence: `README.md`)
- Admin routes → Package prewarming: routes prewarm (evidence: `crates/ferrum/src/admin/routes.rs`)
- Admin user → Storage dashboard: views storage (evidence: `README.md`)
- Storage dashboard → Dashboard API client: calls storage API (evidence: `ui/src/lib/components/StoragePage.svelte`)
- Dashboard API client → Admin routes: sends admin requests
