# unight0/lorebox architecture

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

- Interactive diagram: https://gitdiagram.com/unight0/lorebox
- Repository: https://github.com/unight0/lorebox

## Overview

Lorebox is a single-binary Git server that serves both as a pull-through mirror and, optionally, a host for user-owned repositories. Git clients request repositories through the server; misses are cloned from upstream and cached, while cached repositories are served using Git’s smart HTTP protocol or a dumb-protocol fallback. Owners and administrators also manage repositories through authenticated APIs and matching CLI commands. The graph includes documented refresh, eviction, auth, browsing, and TLS capabilities. Several server subsystems are described in the README but their implementation was not sampled, so those links cite the documentation.

Main entry points: [`main.go`](https://github.com/unight0/lorebox/blob/master/main.go) (HTTP server), [`api.go`](https://github.com/unight0/lorebox/blob/master/api.go) (Admin API), [`git.go`](https://github.com/unight0/lorebox/blob/master/git.go) (Git repository operations), [`client.go`](https://github.com/unight0/lorebox/blob/master/client.go) (Remote-control CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serve["Git serving"]
  node_server["HTTP server<br/>[main.go]"]
  node_pullthrough["Pull-through fetch<br/>[main.go]"]
  node_smart_http["Smart HTTP<br/>[main.go]"]
  node_dumb_http["Dumb HTTP<br/>[dumb.go]"]
  node_repo_index["Repository browsing<br/>[pages.go]"]
end

subgraph group_repos["Repository lifecycle"]
  node_repo_store[("Repository store")]
  node_repo_ops["Git repository operations<br/>[git.go]"]
  node_refresh["Background refresh<br/>[main.go]"]
  node_disk_budget["Disk budget and eviction<br/>[main.go]"]
end

subgraph group_control["Remote control"]
  node_cli["Remote-control CLI<br/>[client.go]"]
  node_admin_api["Admin API<br/>[api.go]"]
  node_owner_api["Self-hosted API<br/>[api.go]"]
  node_auth["Token authentication<br/>[main.go]"]
  node_credential_helper["Git credential helper<br/>[client.go]"]
end

subgraph group_runtime["Runtime support"]
  node_tls["HTTPS and TLS reload<br/>[tls.go]"]
  node_git_backend["Git HTTP backend"]
end

node_git_clients(("Git clients"))
node_upstream(("Upstream Git hosts"))
node_admin(("Admins and owners"))

node_git_clients -->|"requests repositories"| node_server
node_server -->|"fetches cache misses"| node_pullthrough
node_pullthrough -->|"clones upstream"| node_upstream
node_pullthrough -->|"caches mirrors"| node_repo_store
node_server -->|"routes smart requests"| node_smart_http
node_smart_http -->|"serves Git protocol"| node_git_backend
node_server -->|"routes fallback requests"| node_dumb_http
node_dumb_http -->|"reads repository files"| node_repo_store
node_server -->|"initializes repositories"| node_repo_ops
node_repo_ops -->|"updates repository metadata"| node_repo_store
node_refresh -->|"refreshes mirrors"| node_repo_store
node_disk_budget -->|"evicts eligible mirrors"| node_repo_store
node_admin -->|"runs commands"| node_cli
node_cli -->|"sends admin requests"| node_admin_api
node_admin_api -->|"pins repositories"| node_repo_ops
node_admin_api -->|"requests fetch or refresh"| node_pullthrough
node_admin_api -->|"requests eviction"| node_disk_budget
node_cli -->|"sends owner requests"| node_owner_api
node_owner_api -->|"creates Git repositories"| node_repo_ops
node_owner_api -->|"deletes hosted repositories"| node_repo_store
node_server -->|"authorizes requests"| node_auth
node_credential_helper -->|"supplies Git credentials"| node_server
node_server -->|"serves repository listings"| node_repo_index
node_server -->|"serves HTTPS"| node_tls

click node_server "https://github.com/unight0/lorebox/blob/master/main.go"
click node_pullthrough "https://github.com/unight0/lorebox/blob/master/main.go"
click node_smart_http "https://github.com/unight0/lorebox/blob/master/main.go"
click node_dumb_http "https://github.com/unight0/lorebox/blob/master/dumb.go"
click node_repo_ops "https://github.com/unight0/lorebox/blob/master/git.go"
click node_refresh "https://github.com/unight0/lorebox/blob/master/main.go"
click node_disk_budget "https://github.com/unight0/lorebox/blob/master/main.go"
click node_cli "https://github.com/unight0/lorebox/blob/master/client.go"
click node_admin_api "https://github.com/unight0/lorebox/blob/master/api.go"
click node_owner_api "https://github.com/unight0/lorebox/blob/master/api.go"
click node_auth "https://github.com/unight0/lorebox/blob/master/main.go"
click node_credential_helper "https://github.com/unight0/lorebox/blob/master/client.go"
click node_repo_index "https://github.com/unight0/lorebox/blob/master/pages.go"
click node_tls "https://github.com/unight0/lorebox/blob/master/tls.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_server,node_pullthrough,node_smart_http,node_dumb_http,node_repo_index,node_git_clients toneBlue
class node_repo_store,node_repo_ops,node_refresh,node_disk_budget toneAmber
class node_cli,node_admin_api,node_owner_api,node_auth,node_credential_helper toneMint
class node_tls,node_git_backend toneRose
class node_upstream,node_admin toneIndigo
```

## Components

### Git serving

- [HTTP server](https://github.com/unight0/lorebox/blob/master/main.go): `main.go`
- [Pull-through fetch](https://github.com/unight0/lorebox/blob/master/main.go): `main.go`
- [Smart HTTP](https://github.com/unight0/lorebox/blob/master/main.go): `main.go`
- [Dumb HTTP](https://github.com/unight0/lorebox/blob/master/dumb.go): `dumb.go`
- [Repository browsing](https://github.com/unight0/lorebox/blob/master/pages.go): `pages.go`

### Repository lifecycle

- **Repository store**
- [Git repository operations](https://github.com/unight0/lorebox/blob/master/git.go): `git.go`
- [Background refresh](https://github.com/unight0/lorebox/blob/master/main.go): `main.go`
- [Disk budget and eviction](https://github.com/unight0/lorebox/blob/master/main.go): `main.go`

### Remote control

- [Remote-control CLI](https://github.com/unight0/lorebox/blob/master/client.go): `client.go`
- [Admin API](https://github.com/unight0/lorebox/blob/master/api.go): `api.go`
- [Self-hosted API](https://github.com/unight0/lorebox/blob/master/api.go): `api.go`
- [Token authentication](https://github.com/unight0/lorebox/blob/master/main.go): `main.go`
- [Git credential helper](https://github.com/unight0/lorebox/blob/master/client.go): `client.go`

### Runtime support

- [HTTPS and TLS reload](https://github.com/unight0/lorebox/blob/master/tls.go): `tls.go`
- **Git HTTP backend**

### Other components

- **Git clients**
- **Upstream Git hosts**
- **Admins and owners**

## Connections

- Git clients → HTTP server: requests repositories (evidence: `README.md`)
- HTTP server → Pull-through fetch: fetches cache misses (evidence: `main.go`)
- Pull-through fetch → Upstream Git hosts: clones upstream (evidence: `README.md`)
- Pull-through fetch → Repository store: caches mirrors (evidence: `README.md`)
- HTTP server → Smart HTTP: routes smart requests (evidence: `main.go`)
- Smart HTTP → Git HTTP backend: serves Git protocol (evidence: `README.md`)
- HTTP server → Dumb HTTP: routes fallback requests (evidence: `main.go`)
- Dumb HTTP → Repository store: reads repository files (evidence: `dumb.go`)
- HTTP server → Git repository operations: initializes repositories (evidence: `main.go`)
- Git repository operations → Repository store: updates repository metadata (evidence: `git.go`)
- Background refresh → Repository store: refreshes mirrors (evidence: `README.md`)
- Disk budget and eviction → Repository store: evicts eligible mirrors (evidence: `main.go`)
- Admins and owners → Remote-control CLI: runs commands (evidence: `README.md`)
- Remote-control CLI → Admin API: sends admin requests (evidence: `README.md`)
- Admin API → Git repository operations: pins repositories (evidence: `api.go`)
- Admin API → Pull-through fetch: requests fetch or refresh (evidence: `api.go`)
- Admin API → Disk budget and eviction: requests eviction (evidence: `README.md`)
- Remote-control CLI → Self-hosted API: sends owner requests (evidence: `README.md`)
- Self-hosted API → Git repository operations: creates Git repositories (evidence: `api.go`)
- Self-hosted API → Repository store: deletes hosted repositories (evidence: `api.go`)
- HTTP server → Token authentication: authorizes requests (evidence: `README.md`)
- Git credential helper → HTTP server: supplies Git credentials (evidence: `README.md`)
- HTTP server → Repository browsing: serves repository listings (evidence: `README.md`)
- HTTP server → HTTPS and TLS reload: serves HTTPS (evidence: `README.md`)