# garethgeorge/backrest architecture

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

- Interactive diagram: https://gitdiagram.com/garethgeorge/backrest
- Repository: https://github.com/garethgeorge/backrest

## Overview

Backrest is a web-accessible restic backup manager. Users configure repositories and plans in the WebUI, submit backup or maintenance work, and inspect operation history, status, and snapshots; they can also browse and restore files. The backend exposes Connect APIs, persists configuration and operation history, and schedules repository tasks that invoke restic. The README also documents notifications, command hooks, remote-instance synchronization, and multiple storage backends. Connections for unsampled capabilities are included only where documented; source excerpts do not reveal every runtime wiring detail.

Main entry points: [`internal/api/backresthandler.go`](https://github.com/garethgeorge/backrest/blob/main/internal/api/backresthandler.go) (Backup API), [`internal/orchestrator/orchestrator.go`](https://github.com/garethgeorge/backrest/blob/main/internal/orchestrator/orchestrator.go) (Task orchestration), [`webui/src/api/client.ts`](https://github.com/garethgeorge/backrest/blob/main/webui/src/api/client.ts) (API client), [`internal/api/syncapi/syncclient.go`](https://github.com/garethgeorge/backrest/blob/main/internal/api/syncapi/syncclient.go) (Peer sync client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_features["Backup UI"]
  node_dashboard["Dashboard and activity"]
  node_webclient["API client<br/>[client.ts]"]
  node_webstate["UI state and aggregation"]
  node_protocols["Client protocol types"]
end

subgraph group_api["API and identity"]
  node_apihandler["Backup API<br/>[backresthandler.go]"]
  node_authhandler["Authentication API"]
  node_auth["Authentication<br/>[auth.go]"]
end

subgraph group_backup["Backup operations"]
  node_orchestrator["Task orchestration<br/>[orchestrator.go]"]
  node_tasks["Repository tasks"]
  node_restic["Restic execution<br/>[restic.go]"]
  node_resticinstall["Restic installation<br/>[resticinstaller.go]"]
end

subgraph group_state["Configuration and history"]
  node_config[("Config storage")]
  node_oplog[("Operation history<br/>[oplog.go]")]
  node_logs[("Operation logs<br/>[logstore.go]")]
end

subgraph group_sync["Remote synchronization"]
  node_syncmanager["Sync manager<br/>[syncmanager.go]"]
  node_syncclient["Peer sync client<br/>[syncclient.go]"]
end

node_user(("User"))
node_peer(("Remote Backrest instance"))
node_resticrepo[("Restic repository")]

node_user -->|"uses"| node_webapp
node_webapp -->|"shows"| node_features
node_features -.->|"requests"| node_webclient
node_dashboard -->|"aggregates"| node_webstate
node_webclient -->|"uses types"| node_protocols
node_webclient -.->|"calls API"| node_apihandler
node_apihandler -->|"reads/writes"| node_config
node_apihandler -->|"schedules tasks"| node_orchestrator
node_apihandler -->|"queries history"| node_oplog
node_apihandler -->|"streams logs"| node_logs
node_authhandler -->|"authenticates"| node_auth
node_orchestrator -->|"runs tasks"| node_tasks
node_tasks -.->|"invokes restic"| node_restic
node_restic -->|"operates on"| node_resticrepo
node_resticinstall -.->|"provides binary"| node_restic
node_orchestrator -->|"records operations"| node_oplog
node_orchestrator -->|"writes logs"| node_logs
node_syncmanager -->|"watches config"| node_config
node_syncmanager -->|"starts peer sync"| node_syncclient
node_syncclient -->|"syncs with"| node_peer
node_syncclient -->|"transfers history"| node_oplog

click node_webapp "https://github.com/garethgeorge/backrest/blob/main/webui/src/app/App.tsx"
click node_features "https://github.com/garethgeorge/backrest/tree/main/webui/src/features"
click node_dashboard "https://github.com/garethgeorge/backrest/blob/main/webui/src/features/dashboard/SummaryDashboard.tsx"
click node_webclient "https://github.com/garethgeorge/backrest/blob/main/webui/src/api/client.ts"
click node_webstate "https://github.com/garethgeorge/backrest/blob/main/webui/src/api/flowDisplayAggregator.ts"
click node_protocols "https://github.com/garethgeorge/backrest/tree/main/webui/gen/ts"
click node_apihandler "https://github.com/garethgeorge/backrest/blob/main/internal/api/backresthandler.go"
click node_authhandler "https://github.com/garethgeorge/backrest/blob/main/internal/api/authenticationhandler.go"
click node_auth "https://github.com/garethgeorge/backrest/blob/main/internal/auth/auth.go"
click node_orchestrator "https://github.com/garethgeorge/backrest/blob/main/internal/orchestrator/orchestrator.go"
click node_tasks "https://github.com/garethgeorge/backrest/tree/main/internal/orchestrator/tasks"
click node_restic "https://github.com/garethgeorge/backrest/blob/main/pkg/restic/restic.go"
click node_resticinstall "https://github.com/garethgeorge/backrest/blob/main/internal/resticinstaller/resticinstaller.go"
click node_config "https://github.com/garethgeorge/backrest/tree/main/internal/config"
click node_oplog "https://github.com/garethgeorge/backrest/blob/main/internal/oplog/oplog.go"
click node_logs "https://github.com/garethgeorge/backrest/blob/main/internal/logstore/logstore.go"
click node_syncmanager "https://github.com/garethgeorge/backrest/blob/main/internal/api/syncapi/syncmanager.go"
click node_syncclient "https://github.com/garethgeorge/backrest/blob/main/internal/api/syncapi/syncclient.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_webapp,node_features,node_dashboard,node_webclient,node_webstate,node_protocols,node_user toneBlue
class node_apihandler,node_authhandler,node_auth,node_resticrepo toneAmber
class node_orchestrator,node_tasks,node_restic,node_resticinstall toneMint
class node_config,node_oplog,node_logs toneRose
class node_syncmanager,node_syncclient,node_peer toneIndigo
```

## Components

### Web interface

- [Web application](https://github.com/garethgeorge/backrest/blob/main/webui/src/app/App.tsx): `webui/src/app/App.tsx`
- [Backup UI](https://github.com/garethgeorge/backrest/tree/main/webui/src/features): `webui/src/features`
- [Dashboard and activity](https://github.com/garethgeorge/backrest/blob/main/webui/src/features/dashboard/SummaryDashboard.tsx): `webui/src/features/dashboard/SummaryDashboard.tsx`
- [API client](https://github.com/garethgeorge/backrest/blob/main/webui/src/api/client.ts): `webui/src/api/client.ts`
- [UI state and aggregation](https://github.com/garethgeorge/backrest/blob/main/webui/src/api/flowDisplayAggregator.ts): `webui/src/api/flowDisplayAggregator.ts`
- [Client protocol types](https://github.com/garethgeorge/backrest/tree/main/webui/gen/ts): `webui/gen/ts`

### API and identity

- [Backup API](https://github.com/garethgeorge/backrest/blob/main/internal/api/backresthandler.go): `internal/api/backresthandler.go`
- [Authentication API](https://github.com/garethgeorge/backrest/blob/main/internal/api/authenticationhandler.go): `internal/api/authenticationhandler.go`
- [Authentication](https://github.com/garethgeorge/backrest/blob/main/internal/auth/auth.go): `internal/auth/auth.go`

### Backup operations

- [Task orchestration](https://github.com/garethgeorge/backrest/blob/main/internal/orchestrator/orchestrator.go): `internal/orchestrator/orchestrator.go`
- [Repository tasks](https://github.com/garethgeorge/backrest/tree/main/internal/orchestrator/tasks): `internal/orchestrator/tasks`
- [Restic execution](https://github.com/garethgeorge/backrest/blob/main/pkg/restic/restic.go): `pkg/restic/restic.go`
- [Restic installation](https://github.com/garethgeorge/backrest/blob/main/internal/resticinstaller/resticinstaller.go): `internal/resticinstaller/resticinstaller.go`

### Configuration and history

- [Config storage](https://github.com/garethgeorge/backrest/tree/main/internal/config): `internal/config`
- [Operation history](https://github.com/garethgeorge/backrest/blob/main/internal/oplog/oplog.go): `internal/oplog/oplog.go`
- [Operation logs](https://github.com/garethgeorge/backrest/blob/main/internal/logstore/logstore.go): `internal/logstore/logstore.go`

### Remote synchronization

- [Sync manager](https://github.com/garethgeorge/backrest/blob/main/internal/api/syncapi/syncmanager.go): `internal/api/syncapi/syncmanager.go`
- [Peer sync client](https://github.com/garethgeorge/backrest/blob/main/internal/api/syncapi/syncclient.go): `internal/api/syncapi/syncclient.go`

### Other components

- **User**
- **Remote Backrest instance**
- **Restic repository**

## Connections

- User → Web application: uses
- Web application → Backup UI: shows (evidence: `webui/src/app/App.tsx`)
- Backup UI → API client: requests
- Dashboard and activity → UI state and aggregation: aggregates
- API client → Client protocol types: uses types (evidence: `webui/src/api/client.ts`)
- API client → Backup API: calls API
- Backup API → Config storage: reads/writes (evidence: `internal/api/backresthandler.go`)
- Backup API → Task orchestration: schedules tasks (evidence: `internal/api/backresthandler.go`)
- Backup API → Operation history: queries history (evidence: `internal/api/backresthandler.go`)
- Backup API → Operation logs: streams logs (evidence: `internal/api/backresthandler.go`)
- Authentication API → Authentication: authenticates (evidence: `internal/api/authenticationhandler.go`)
- Task orchestration → Repository tasks: runs tasks (evidence: `internal/orchestrator/orchestrator.go`)
- Repository tasks → Restic execution: invokes restic
- Restic execution → Restic repository: operates on
- Restic installation → Restic execution: provides binary
- Task orchestration → Operation history: records operations (evidence: `internal/orchestrator/orchestrator.go`)
- Task orchestration → Operation logs: writes logs (evidence: `internal/orchestrator/orchestrator.go`)
- Sync manager → Config storage: watches config (evidence: `internal/api/syncapi/syncmanager.go`)
- Sync manager → Peer sync client: starts peer sync (evidence: `internal/api/syncapi/syncmanager.go`)
- Peer sync client → Remote Backrest instance: syncs with (evidence: `internal/api/syncapi/syncclient.go`)
- Peer sync client → Operation history: transfers history (evidence: `internal/api/syncapi/syncclient.go`)
