# dbrobot/home-server architecture

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

- Interactive diagram: https://gitdiagram.com/dbrobot/home-server
- Repository: https://github.com/dbrobot/home-server

## Overview

Home-Server is a declarative self-hosted family-server project with Rust services and client tools. A representative user flow is: a person uses the `dd` CLI to manage identity and device credentials, publishes or retrieves signed identity entries through directories, then accesses box-hosted services; the verifier supplies identity-aware access for services such as games. Other documented capabilities include encrypted library/archive storage, media playback and transcoding, games, and encrypted Git remotes. The supplied tree omits the README’s Nix, fleet, and secrets directories, and sampled source is partial, so those deployment internals and uncertain service wiring are not mapped.

Main entry points: [`client/cli/src/main.rs`](https://github.com/dbrobot/home-server/blob/main/client/cli/src/main.rs) (dd CLI), [`box/verify/src/lib.rs`](https://github.com/dbrobot/home-server/blob/main/box/verify/src/lib.rs) (Verifier service), [`app/src/lib.rs`](https://github.com/dbrobot/home-server/blob/main/app/src/lib.rs) (Desktop app), [`box/games/src/main.rs`](https://github.com/dbrobot/home-server/blob/main/box/games/src/main.rs) (Games service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Member clients"]
  node_cli["dd CLI<br/>[main.rs]"]
  node_desktop["Desktop app<br/>[lib.rs]"]
  node_appweb["App pages<br/>[app.js]"]
  node_network["App networking<br/>[net.rs]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Device auth<br/>[lib.rs]"]
  node_identitylib["Signed identity<br/>[lib.rs]"]
  node_directory["Directory client<br/>[lib.rs]"]
  node_verifier["Verifier service<br/>[lib.rs]"]
  node_sessions["Web sessions<br/>[session.rs]"]
end

subgraph group_services["Box services"]
  node_games_web["Games service<br/>[main.rs]"]
  node_games_manager["Game manager<br/>[lib.rs]"]
  node_release["Release agent<br/>[lib.rs]"]
  node_photos["Photos integration<br/>[library.rs]"]
end

subgraph group_media["Media and storage"]
  node_library["Encrypted library<br/>[lib.rs]"]
  node_archive["Archive backend<br/>[lib.rs]"]
  node_media_client["Media client<br/>[lib.rs]"]
  node_transcode["Transcode service<br/>[main.rs]"]
end

subgraph group_collaboration["Shared tools"]
  node_gitremote["Encrypted Git remote<br/>[main.rs]"]
end

node_person(("Member"))
node_browser(("Browser"))
node_external_directory[("Directory servers")]
node_bucket[("Chunk store")]
node_ffmpeg["FFmpeg"]
node_forge[("Git forge")]

node_person -->|"runs commands"| node_cli
node_cli -->|"opens credentials"| node_auth
node_cli -->|"manages identity"| node_identitylib
node_cli -->|"publishes entries"| node_directory
node_directory -->|"reads and writes"| node_external_directory
node_gitremote -->|"fetches entries"| node_external_directory
node_gitremote -->|"verifies signatures"| node_identitylib
node_gitremote -->|"pushes encrypted state"| node_forge
node_person -->|"uses"| node_browser
node_browser -->|"authenticates"| node_verifier
node_verifier -->|"checks identity"| node_identitylib
node_verifier -->|"issues sessions"| node_sessions
node_verifier -.->|"configures photos"| node_photos
node_appweb -->|"invokes commands"| node_desktop
node_desktop -->|"opens keystore"| node_auth
node_desktop -->|"reads entries"| node_directory
node_desktop -->|"controls network"| node_network
node_person -->|"uses via client"| node_library
node_cli -->|"manages archives"| node_archive
node_media_client -->|"opens chunks"| node_library
node_transcode -->|"fetches chunks"| node_bucket
node_transcode -->|"decrypts chunks"| node_library
node_transcode -->|"serves plaintext"| node_ffmpeg
node_browser -->|"requests game service"| node_games_web
node_games_web -->|"manages instances"| node_games_manager
node_games_web -->|"restores worlds"| node_games_manager
node_verifier -.->|"provides user context"| node_games_web
node_cli -->|"uses release commands"| node_release

click node_cli "https://github.com/dbrobot/home-server/blob/main/client/cli/src/main.rs"
click node_desktop "https://github.com/dbrobot/home-server/blob/main/app/src/lib.rs"
click node_appweb "https://github.com/dbrobot/home-server/blob/main/app/web/app.js"
click node_auth "https://github.com/dbrobot/home-server/blob/main/client/auth/src/lib.rs"
click node_identitylib "https://github.com/dbrobot/home-server/blob/main/client/identity/src/lib.rs"
click node_directory "https://github.com/dbrobot/home-server/blob/main/client/directory/src/lib.rs"
click node_verifier "https://github.com/dbrobot/home-server/blob/main/box/verify/src/lib.rs"
click node_sessions "https://github.com/dbrobot/home-server/blob/main/box/verify/src/session.rs"
click node_library "https://github.com/dbrobot/home-server/blob/main/client/library/src/lib.rs"
click node_archive "https://github.com/dbrobot/home-server/blob/main/box/archive/src/lib.rs"
click node_media_client "https://github.com/dbrobot/home-server/blob/main/client/media/src/lib.rs"
click node_transcode "https://github.com/dbrobot/home-server/blob/main/box/transcode/src/main.rs"
click node_games_web "https://github.com/dbrobot/home-server/blob/main/box/games/src/main.rs"
click node_games_manager "https://github.com/dbrobot/home-server/blob/main/box/games/src/lib.rs"
click node_release "https://github.com/dbrobot/home-server/blob/main/box/release/src/lib.rs"
click node_network "https://github.com/dbrobot/home-server/blob/main/app/src/net.rs"
click node_gitremote "https://github.com/dbrobot/home-server/blob/main/client/gitremote/src/main.rs"
click node_photos "https://github.com/dbrobot/home-server/blob/main/box/verify/src/library.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_desktop,node_appweb,node_network,node_browser toneBlue
class node_auth,node_identitylib,node_directory,node_verifier,node_sessions,node_external_directory,node_bucket,node_forge toneAmber
class node_games_web,node_games_manager,node_release,node_photos toneMint
class node_library,node_archive,node_media_client,node_transcode toneRose
class node_gitremote,node_person,node_ffmpeg toneIndigo
```

## Components

### Member clients

- [dd CLI](https://github.com/dbrobot/home-server/blob/main/client/cli/src/main.rs): `client/cli/src/main.rs`
- [Desktop app](https://github.com/dbrobot/home-server/blob/main/app/src/lib.rs): `app/src/lib.rs`
- [App pages](https://github.com/dbrobot/home-server/blob/main/app/web/app.js): `app/web/app.js`
- [App networking](https://github.com/dbrobot/home-server/blob/main/app/src/net.rs): `app/src/net.rs`

### Identity and access

- [Device auth](https://github.com/dbrobot/home-server/blob/main/client/auth/src/lib.rs): `client/auth/src/lib.rs`
- [Signed identity](https://github.com/dbrobot/home-server/blob/main/client/identity/src/lib.rs): `client/identity/src/lib.rs`
- [Directory client](https://github.com/dbrobot/home-server/blob/main/client/directory/src/lib.rs): `client/directory/src/lib.rs`
- [Verifier service](https://github.com/dbrobot/home-server/blob/main/box/verify/src/lib.rs): `box/verify/src/lib.rs`
- [Web sessions](https://github.com/dbrobot/home-server/blob/main/box/verify/src/session.rs): `box/verify/src/session.rs`

### Box services

- [Games service](https://github.com/dbrobot/home-server/blob/main/box/games/src/main.rs): `box/games/src/main.rs`
- [Game manager](https://github.com/dbrobot/home-server/blob/main/box/games/src/lib.rs): `box/games/src/lib.rs`
- [Release agent](https://github.com/dbrobot/home-server/blob/main/box/release/src/lib.rs): `box/release/src/lib.rs`
- [Photos integration](https://github.com/dbrobot/home-server/blob/main/box/verify/src/library.rs): `box/verify/src/library.rs`

### Media and storage

- [Encrypted library](https://github.com/dbrobot/home-server/blob/main/client/library/src/lib.rs): `client/library/src/lib.rs`
- [Archive backend](https://github.com/dbrobot/home-server/blob/main/box/archive/src/lib.rs): `box/archive/src/lib.rs`
- [Media client](https://github.com/dbrobot/home-server/blob/main/client/media/src/lib.rs): `client/media/src/lib.rs`
- [Transcode service](https://github.com/dbrobot/home-server/blob/main/box/transcode/src/main.rs): `box/transcode/src/main.rs`

### Shared tools

- [Encrypted Git remote](https://github.com/dbrobot/home-server/blob/main/client/gitremote/src/main.rs): `client/gitremote/src/main.rs`

### Other components

- **Member**
- **Browser**
- **Directory servers**
- **Chunk store**
- **FFmpeg**
- **Git forge**

## Connections

- Member → dd CLI: runs commands
- dd CLI → Device auth: opens credentials
- dd CLI → Signed identity: manages identity
- dd CLI → Directory client: publishes entries
- Directory client → Directory servers: reads and writes
- Encrypted Git remote → Directory servers: fetches entries
- Encrypted Git remote → Signed identity: verifies signatures
- Encrypted Git remote → Git forge: pushes encrypted state
- Member → Browser: uses
- Browser → Verifier service: authenticates
- Verifier service → Signed identity: checks identity
- Verifier service → Web sessions: issues sessions
- Verifier service → Photos integration: configures photos
- App pages → Desktop app: invokes commands
- Desktop app → Device auth: opens keystore
- Desktop app → Directory client: reads entries
- Desktop app → App networking: controls network
- Member → Encrypted library: uses via client
- dd CLI → Archive backend: manages archives
- Media client → Encrypted library: opens chunks
- Transcode service → Chunk store: fetches chunks
- Transcode service → Encrypted library: decrypts chunks
- Transcode service → FFmpeg: serves plaintext
- Browser → Games service: requests game service
- Games service → Game manager: manages instances
- Games service → Game manager: restores worlds
- Verifier service → Games service: provides user context
- dd CLI → Release agent: uses release commands