# darwintjoe/dbhub architecture

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

- Interactive diagram: https://gitdiagram.com/darwintjoe/dbhub
- Repository: https://github.com/darwintjoe/dbhub

## Overview

DBHub is a standalone LAN sync hub: devices submit ledger bundles, which the hub validates and records in a verified local chain, then exposes through device pull/manifest APIs and a read-only admin dashboard. The product also covers device pairing and management, quarantine and maintenance, monitoring, backups, configuration, and optional connectivity/replica modes. Edges are limited to relationships visible in excerpts, the SOURCE INDEX, or README; several route and integration details are unsampled, so those links are omitted.

Main entry points: [`src/services/ingest.ts`](https://github.com/darwintjoe/dbhub/blob/main/src/services/ingest.ts) (Bundle Ingest), [`src/server.ts`](https://github.com/darwintjoe/dbhub/blob/main/src/server.ts) (Service Runtime), [`src/http/routes/admin-extra.ts`](https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/admin-extra.ts) (Admin API Routes), [`src/app.ts`](https://github.com/darwintjoe/dbhub/blob/main/src/app.ts) (HTTP Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Device Sync"]
  node_devices["Devices<br/>[devices.ts]"]
  node_pairing["Pairing<br/>[pairings.ts]"]
  node_bundle_ingest["Bundle Ingest<br/>[ingest.ts]"]
  node_sync_routes["Sync Routes<br/>[relay.ts]"]
  node_pull_manifest["Pull &amp; Manifest<br/>[pull.ts]"]
  node_chain_logic["Chain Verification<br/>[chain.ts]"]
  node_hashing["Canonical Hashing<br/>[hashing.ts]"]
  node_validation["Bundle Validation<br/>[validation.ts]"]
end

subgraph group_state["Local State"]
  node_sqlite[("SQLite Database<br/>[database.ts]")]
  node_device_repo["Device Records<br/>[devices.repo.ts]"]
  node_bundle_repo["Bundle Records<br/>[bundles.repo.ts]"]
  node_manifest_repo["Manifest Records<br/>[manifests.repo.ts]"]
  node_outbox_repo["Replica Outbox<br/>[outbox.repo.ts]"]
  node_replica["Replica Targets"]
end

subgraph group_admin["Admin Experience"]
  node_admin_ui["Admin Dashboard<br/>[app.js]"]
  node_admin_api["Admin API Routes<br/>[admin-extra.ts]"]
  node_admin_auth["Admin Sessions<br/>[admin-session.ts]"]
  node_config_service["Config Management<br/>[config-service.ts]"]
end

subgraph group_ops["Operations"]
  node_monitoring["Host Monitoring<br/>[sampler.ts]"]
  node_overview["Hub Overview<br/>[overview.ts]"]
  node_maintenance["Maintenance<br/>[maintenance.ts]"]
  node_backup["Backups<br/>[backup.ts]"]
  node_connectivity["Connectivity<br/>[connectivity.ts]"]
  node_cloudflare["Cloudflare Tunnel"]
  node_mdns["mDNS Discovery<br/>[mdns.ts]"]
end

subgraph group_platform["Runtime"]
  node_config["Runtime Config<br/>[config.ts]"]
  node_app["HTTP Application<br/>[app.ts]"]
  node_server["Service Runtime<br/>[server.ts]"]
end

node_device_actor(("Sync Devices"))
node_admin_actor(("Administrator"))

node_device_actor -->|"submits sync"| node_app
node_app -->|"routes claims"| node_pairing
node_app -->|"routes relay"| node_sync_routes
node_app -->|"routes pull"| node_pull_manifest
node_sync_routes -->|"invokes ingest"| node_bundle_ingest
node_bundle_ingest -->|"validates bundles"| node_validation
node_bundle_ingest -->|"computes hashes"| node_hashing
node_bundle_ingest -->|"checks continuity"| node_chain_logic
node_bundle_ingest -->|"stores bundles"| node_bundle_repo
node_bundle_ingest -->|"reads device state"| node_device_repo
node_bundle_ingest -->|"uses manifests"| node_manifest_repo
node_bundle_ingest -->|"queues replicas"| node_outbox_repo
node_pull_manifest -->|"reads bundles"| node_bundle_repo
node_server -->|"opens database"| node_sqlite
node_server -->|"creates repository"| node_device_repo
node_server -->|"creates repository"| node_bundle_repo
node_server -->|"creates repository"| node_manifest_repo
node_server -->|"creates repository"| node_outbox_repo
node_server -->|"starts application"| node_app
node_server -->|"loads settings"| node_config
node_admin_actor -->|"uses dashboard"| node_admin_ui
node_admin_ui -.->|"requests overview"| node_admin_api
node_app -->|"guards admin routes"| node_admin_auth
node_admin_api -->|"uses config service"| node_config_service
node_admin_api -->|"reads samples"| node_monitoring
node_admin_api -->|"reads overview"| node_overview
node_admin_api -->|"uses backup service"| node_backup
node_admin_api -->|"routes maintenance"| node_maintenance
node_config -.->|"configures mode"| node_connectivity
node_config -->|"selects target"| node_replica
node_connectivity -.->|"optionally starts"| node_cloudflare
node_connectivity -.->|"optionally advertises"| node_mdns

click node_devices "https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/devices.ts"
click node_pairing "https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/pairings.ts"
click node_bundle_ingest "https://github.com/darwintjoe/dbhub/blob/main/src/services/ingest.ts"
click node_sync_routes "https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/relay.ts"
click node_pull_manifest "https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/pull.ts"
click node_chain_logic "https://github.com/darwintjoe/dbhub/blob/main/src/domain/chain.ts"
click node_hashing "https://github.com/darwintjoe/dbhub/blob/main/src/domain/hashing.ts"
click node_validation "https://github.com/darwintjoe/dbhub/blob/main/src/domain/validation.ts"
click node_sqlite "https://github.com/darwintjoe/dbhub/blob/main/src/db/database.ts"
click node_device_repo "https://github.com/darwintjoe/dbhub/blob/main/src/db/devices.repo.ts"
click node_bundle_repo "https://github.com/darwintjoe/dbhub/blob/main/src/db/bundles.repo.ts"
click node_manifest_repo "https://github.com/darwintjoe/dbhub/blob/main/src/db/manifests.repo.ts"
click node_outbox_repo "https://github.com/darwintjoe/dbhub/blob/main/src/db/outbox.repo.ts"
click node_replica "https://github.com/darwintjoe/dbhub/tree/main/src/services/replica"
click node_admin_ui "https://github.com/darwintjoe/dbhub/blob/main/public/admin/app.js"
click node_admin_api "https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/admin-extra.ts"
click node_admin_auth "https://github.com/darwintjoe/dbhub/blob/main/src/http/admin-session.ts"
click node_config_service "https://github.com/darwintjoe/dbhub/blob/main/src/services/config-service.ts"
click node_monitoring "https://github.com/darwintjoe/dbhub/blob/main/src/services/metrics/sampler.ts"
click node_overview "https://github.com/darwintjoe/dbhub/blob/main/src/services/overview.ts"
click node_maintenance "https://github.com/darwintjoe/dbhub/blob/main/src/services/maintenance.ts"
click node_backup "https://github.com/darwintjoe/dbhub/blob/main/src/services/backup.ts"
click node_connectivity "https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/connectivity.ts"
click node_cloudflare "https://github.com/darwintjoe/dbhub/blob/main/src/services/cloudflare-tunnel.ts"
click node_mdns "https://github.com/darwintjoe/dbhub/blob/main/src/services/mdns.ts"
click node_config "https://github.com/darwintjoe/dbhub/blob/main/src/config.ts"
click node_app "https://github.com/darwintjoe/dbhub/blob/main/src/app.ts"
click node_server "https://github.com/darwintjoe/dbhub/blob/main/src/server.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_devices,node_pairing,node_bundle_ingest,node_sync_routes,node_pull_manifest,node_chain_logic,node_hashing,node_validation toneBlue
class node_sqlite,node_device_repo,node_bundle_repo,node_manifest_repo,node_outbox_repo,node_replica toneAmber
class node_admin_ui,node_admin_api,node_admin_auth,node_config_service toneMint
class node_monitoring,node_overview,node_maintenance,node_backup,node_connectivity,node_cloudflare,node_mdns toneRose
class node_config,node_app,node_server,node_device_actor,node_admin_actor toneIndigo
```

## Components

### Device Sync

- [Devices](https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/devices.ts): `src/http/routes/devices.ts`
- [Pairing](https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/pairings.ts): `src/http/routes/pairings.ts`
- [Bundle Ingest](https://github.com/darwintjoe/dbhub/blob/main/src/services/ingest.ts): `src/services/ingest.ts`
- [Sync Routes](https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/relay.ts): `src/http/routes/relay.ts`
- [Pull & Manifest](https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/pull.ts): `src/http/routes/pull.ts`
- [Chain Verification](https://github.com/darwintjoe/dbhub/blob/main/src/domain/chain.ts): `src/domain/chain.ts`
- [Canonical Hashing](https://github.com/darwintjoe/dbhub/blob/main/src/domain/hashing.ts): `src/domain/hashing.ts`
- [Bundle Validation](https://github.com/darwintjoe/dbhub/blob/main/src/domain/validation.ts): `src/domain/validation.ts`

### Local State

- [SQLite Database](https://github.com/darwintjoe/dbhub/blob/main/src/db/database.ts): `src/db/database.ts`
- [Device Records](https://github.com/darwintjoe/dbhub/blob/main/src/db/devices.repo.ts): `src/db/devices.repo.ts`
- [Bundle Records](https://github.com/darwintjoe/dbhub/blob/main/src/db/bundles.repo.ts): `src/db/bundles.repo.ts`
- [Manifest Records](https://github.com/darwintjoe/dbhub/blob/main/src/db/manifests.repo.ts): `src/db/manifests.repo.ts`
- [Replica Outbox](https://github.com/darwintjoe/dbhub/blob/main/src/db/outbox.repo.ts): `src/db/outbox.repo.ts`
- [Replica Targets](https://github.com/darwintjoe/dbhub/tree/main/src/services/replica): `src/services/replica`

### Admin Experience

- [Admin Dashboard](https://github.com/darwintjoe/dbhub/blob/main/public/admin/app.js): `public/admin/app.js`
- [Admin API Routes](https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/admin-extra.ts): `src/http/routes/admin-extra.ts`
- [Admin Sessions](https://github.com/darwintjoe/dbhub/blob/main/src/http/admin-session.ts): `src/http/admin-session.ts`
- [Config Management](https://github.com/darwintjoe/dbhub/blob/main/src/services/config-service.ts): `src/services/config-service.ts`

### Operations

- [Host Monitoring](https://github.com/darwintjoe/dbhub/blob/main/src/services/metrics/sampler.ts): `src/services/metrics/sampler.ts`
- [Hub Overview](https://github.com/darwintjoe/dbhub/blob/main/src/services/overview.ts): `src/services/overview.ts`
- [Maintenance](https://github.com/darwintjoe/dbhub/blob/main/src/services/maintenance.ts): `src/services/maintenance.ts`
- [Backups](https://github.com/darwintjoe/dbhub/blob/main/src/services/backup.ts): `src/services/backup.ts`
- [Connectivity](https://github.com/darwintjoe/dbhub/blob/main/src/http/routes/connectivity.ts): `src/http/routes/connectivity.ts`
- [Cloudflare Tunnel](https://github.com/darwintjoe/dbhub/blob/main/src/services/cloudflare-tunnel.ts): `src/services/cloudflare-tunnel.ts`
- [mDNS Discovery](https://github.com/darwintjoe/dbhub/blob/main/src/services/mdns.ts): `src/services/mdns.ts`

### Runtime

- [Runtime Config](https://github.com/darwintjoe/dbhub/blob/main/src/config.ts): `src/config.ts`
- [HTTP Application](https://github.com/darwintjoe/dbhub/blob/main/src/app.ts): `src/app.ts`
- [Service Runtime](https://github.com/darwintjoe/dbhub/blob/main/src/server.ts): `src/server.ts`

### Other components

- **Sync Devices**
- **Administrator**

## Connections

- Sync Devices → HTTP Application: submits sync (evidence: `README.md`)
- HTTP Application → Pairing: routes claims (evidence: `src/app.ts`)
- HTTP Application → Sync Routes: routes relay (evidence: `src/app.ts`)
- HTTP Application → Pull & Manifest: routes pull (evidence: `src/app.ts`)
- Sync Routes → Bundle Ingest: invokes ingest (evidence: `src/app.ts`)
- Bundle Ingest → Bundle Validation: validates bundles (evidence: `src/services/ingest.ts`)
- Bundle Ingest → Canonical Hashing: computes hashes (evidence: `src/services/ingest.ts`)
- Bundle Ingest → Chain Verification: checks continuity (evidence: `src/services/ingest.ts`)
- Bundle Ingest → Bundle Records: stores bundles (evidence: `src/services/ingest.ts`)
- Bundle Ingest → Device Records: reads device state (evidence: `src/services/ingest.ts`)
- Bundle Ingest → Manifest Records: uses manifests (evidence: `src/services/ingest.ts`)
- Bundle Ingest → Replica Outbox: queues replicas (evidence: `src/services/ingest.ts`)
- Pull & Manifest → Bundle Records: reads bundles (evidence: `src/app.ts`)
- Service Runtime → SQLite Database: opens database (evidence: `src/server.ts`)
- Service Runtime → Device Records: creates repository (evidence: `src/server.ts`)
- Service Runtime → Bundle Records: creates repository (evidence: `src/server.ts`)
- Service Runtime → Manifest Records: creates repository (evidence: `src/server.ts`)
- Service Runtime → Replica Outbox: creates repository (evidence: `src/server.ts`)
- Service Runtime → HTTP Application: starts application (evidence: `src/server.ts`)
- Service Runtime → Runtime Config: loads settings (evidence: `src/server.ts`)
- Administrator → Admin Dashboard: uses dashboard (evidence: `README.md`)
- Admin Dashboard → Admin API Routes: requests overview
- HTTP Application → Admin Sessions: guards admin routes (evidence: `src/app.ts`)
- Admin API Routes → Config Management: uses config service (evidence: `src/http/routes/admin-extra.ts`)
- Admin API Routes → Host Monitoring: reads samples (evidence: `src/http/routes/admin-extra.ts`)
- Admin API Routes → Hub Overview: reads overview (evidence: `src/http/routes/admin-extra.ts`)
- Admin API Routes → Backups: uses backup service (evidence: `src/http/routes/admin-extra.ts`)
- Admin API Routes → Maintenance: routes maintenance
- Runtime Config → Connectivity: configures mode
- Runtime Config → Replica Targets: selects target (evidence: `src/config.ts`)
- Connectivity → Cloudflare Tunnel: optionally starts
- Connectivity → mDNS Discovery: optionally advertises
