# chrisb0-2/storage-sage architecture

> Architecture diagram of the GitHub repository chrisb0-2/storage-sage, 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/chrisb0-2/storage-sage
- Repository: https://github.com/chrisb0-2/storage-sage

## Overview

Storage-Sage is a safety-first disk-cleanup service with both one-shot CLI and scheduled daemon operation, plus a browser dashboard. Its main workflow scans configured roots, evaluates cleanup policy and filesystem safety, then previews or executes actions; execution can move files to recoverable trash, with decisions retained in an audit trail. The graph preserves the documented safety gates and the dashboard’s monitoring and management capabilities. Some workflow links rely on README documentation because the relevant implementation excerpts are incomplete.

Main entry points: [`cmd/storage-sage/main.go`](https://github.com/chrisb0-2/storage-sage/blob/main/cmd/storage-sage/main.go) (CLI entry point), [`internal/executor/simple.go`](https://github.com/chrisb0-2/storage-sage/blob/main/internal/executor/simple.go) (Fail-closed executor), [`internal/daemon/daemon.go`](https://github.com/chrisb0-2/storage-sage/blob/main/internal/daemon/daemon.go) (Daemon scheduler), [`web/src/pages`](https://github.com/chrisb0-2/storage-sage/tree/main/web/src/pages) (Dashboard pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cleanup["Cleanup workflow"]
  node_cli["CLI entry point<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_scanner["Filesystem scanner<br/>[walkdir.go]"]
  node_policy["Cleanup policies"]
  node_safety["Safety validation<br/>[safety.go]"]
  node_ancestor["Ancestor checks"]
  node_planner["Action planner<br/>[planner.go]"]
  node_executor["Fail-closed executor<br/>[simple.go]"]
end

subgraph group_daemon["Service and API"]
  node_daemon["Daemon scheduler<br/>[daemon.go]"]
  node_auth["API authentication"]
  node_web["Embedded web app<br/>[embed.go]"]
end

subgraph group_webui["Web dashboard"]
  node_api["HTTP API client<br/>[client.ts]"]
  node_dashboard["Dashboard pages"]
  node_uihooks["Data hooks"]
  node_uicomponents["Dashboard components"]
end

subgraph group_operations["State and observability"]
  node_trash[("Soft-delete store<br/>[trash.go]")]
  node_audit[("Audit trail")]
  node_metrics["Prometheus metrics<br/>[prometheus.go]"]
  node_notifier["Webhook notifications<br/>[webhook.go]"]
  node_logger["Application logging"]
end

node_admin(("Administrator"))

node_admin -->|"configures cleanup"| node_cli
node_admin -->|"operates service"| node_daemon
node_cli -->|"loads settings"| node_config
node_cli -->|"starts scan"| node_scanner
node_scanner -->|"candidates evaluated"| node_policy
node_policy -->|"passes candidates"| node_safety
node_safety -->|"checks ancestry"| node_ancestor
node_ancestor -->|"cleared for planning"| node_planner
node_planner -->|"supplies plan"| node_executor
node_cli -->|"executes plan"| node_executor
node_executor -->|"revalidates before mutation"| node_safety
node_executor -->|"moves to trash"| node_trash
node_executor -->|"records result"| node_audit
node_daemon -->|"runs cleanup callback"| node_cli
node_admin -->|"views and manages"| node_dashboard
node_dashboard -->|"uses data hooks"| node_uihooks
node_dashboard -->|"renders controls"| node_uicomponents
node_uihooks -->|"requests data"| node_api
node_api -->|"calls HTTP endpoints"| node_daemon
node_daemon -->|"queries audit records"| node_audit
node_daemon -->|"manages trash items"| node_trash
node_daemon -.->|"protects API"| node_auth
node_cli -->|"starts metrics service"| node_metrics
node_executor -->|"records action metrics"| node_metrics
node_cli -.->|"configures notifications"| node_notifier
node_cli -.->|"configures logging"| node_logger

click node_cli "https://github.com/chrisb0-2/storage-sage/blob/main/cmd/storage-sage/main.go"
click node_config "https://github.com/chrisb0-2/storage-sage/blob/main/internal/config/config.go"
click node_scanner "https://github.com/chrisb0-2/storage-sage/blob/main/internal/scanner/walkdir.go"
click node_policy "https://github.com/chrisb0-2/storage-sage/tree/main/internal/policy"
click node_safety "https://github.com/chrisb0-2/storage-sage/blob/main/internal/safety/safety.go"
click node_ancestor "https://github.com/chrisb0-2/storage-sage/blob/main/internal/safety/ancestor_symlink.go"
click node_planner "https://github.com/chrisb0-2/storage-sage/blob/main/internal/planner/planner.go"
click node_executor "https://github.com/chrisb0-2/storage-sage/blob/main/internal/executor/simple.go"
click node_trash "https://github.com/chrisb0-2/storage-sage/blob/main/internal/trash/trash.go"
click node_daemon "https://github.com/chrisb0-2/storage-sage/blob/main/internal/daemon/daemon.go"
click node_auth "https://github.com/chrisb0-2/storage-sage/tree/main/internal/auth"
click node_web "https://github.com/chrisb0-2/storage-sage/blob/main/internal/web/embed.go"
click node_api "https://github.com/chrisb0-2/storage-sage/blob/main/web/src/api/client.ts"
click node_dashboard "https://github.com/chrisb0-2/storage-sage/tree/main/web/src/pages"
click node_uihooks "https://github.com/chrisb0-2/storage-sage/tree/main/web/src/hooks"
click node_uicomponents "https://github.com/chrisb0-2/storage-sage/tree/main/web/src/components"
click node_audit "https://github.com/chrisb0-2/storage-sage/tree/main/internal/auditor"
click node_metrics "https://github.com/chrisb0-2/storage-sage/blob/main/internal/metrics/prometheus.go"
click node_notifier "https://github.com/chrisb0-2/storage-sage/blob/main/internal/notifier/webhook.go"
click node_logger "https://github.com/chrisb0-2/storage-sage/tree/main/internal/logger"

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_config,node_scanner,node_policy,node_safety,node_ancestor,node_planner,node_executor toneBlue
class node_daemon,node_auth,node_web toneAmber
class node_api,node_dashboard,node_uihooks,node_uicomponents toneMint
class node_trash,node_audit,node_metrics,node_notifier,node_logger toneRose
class node_admin toneIndigo
```

## Components

### Cleanup workflow

- [CLI entry point](https://github.com/chrisb0-2/storage-sage/blob/main/cmd/storage-sage/main.go): `cmd/storage-sage/main.go`
- [Configuration](https://github.com/chrisb0-2/storage-sage/blob/main/internal/config/config.go): `internal/config/config.go`
- [Filesystem scanner](https://github.com/chrisb0-2/storage-sage/blob/main/internal/scanner/walkdir.go): `internal/scanner/walkdir.go`
- [Cleanup policies](https://github.com/chrisb0-2/storage-sage/tree/main/internal/policy): `internal/policy`
- [Safety validation](https://github.com/chrisb0-2/storage-sage/blob/main/internal/safety/safety.go): `internal/safety/safety.go`
- [Ancestor checks](https://github.com/chrisb0-2/storage-sage/blob/main/internal/safety/ancestor_symlink.go): `internal/safety/ancestor_symlink.go`
- [Action planner](https://github.com/chrisb0-2/storage-sage/blob/main/internal/planner/planner.go): `internal/planner/planner.go`
- [Fail-closed executor](https://github.com/chrisb0-2/storage-sage/blob/main/internal/executor/simple.go): `internal/executor/simple.go`

### Service and API

- [Daemon scheduler](https://github.com/chrisb0-2/storage-sage/blob/main/internal/daemon/daemon.go): `internal/daemon/daemon.go`
- [API authentication](https://github.com/chrisb0-2/storage-sage/tree/main/internal/auth): `internal/auth`
- [Embedded web app](https://github.com/chrisb0-2/storage-sage/blob/main/internal/web/embed.go): `internal/web/embed.go`

### Web dashboard

- [HTTP API client](https://github.com/chrisb0-2/storage-sage/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Dashboard pages](https://github.com/chrisb0-2/storage-sage/tree/main/web/src/pages): `web/src/pages`
- [Data hooks](https://github.com/chrisb0-2/storage-sage/tree/main/web/src/hooks): `web/src/hooks`
- [Dashboard components](https://github.com/chrisb0-2/storage-sage/tree/main/web/src/components): `web/src/components`

### State and observability

- [Soft-delete store](https://github.com/chrisb0-2/storage-sage/blob/main/internal/trash/trash.go): `internal/trash/trash.go`
- [Audit trail](https://github.com/chrisb0-2/storage-sage/tree/main/internal/auditor): `internal/auditor`
- [Prometheus metrics](https://github.com/chrisb0-2/storage-sage/blob/main/internal/metrics/prometheus.go): `internal/metrics/prometheus.go`
- [Webhook notifications](https://github.com/chrisb0-2/storage-sage/blob/main/internal/notifier/webhook.go): `internal/notifier/webhook.go`
- [Application logging](https://github.com/chrisb0-2/storage-sage/tree/main/internal/logger): `internal/logger`

### Other components

- **Administrator**

## Connections

- Administrator → CLI entry point: configures cleanup (evidence: `README.md`)
- Administrator → Daemon scheduler: operates service (evidence: `README.md`)
- CLI entry point → Configuration: loads settings (evidence: `cmd/storage-sage/main.go`)
- CLI entry point → Filesystem scanner: starts scan (evidence: `README.md`)
- Filesystem scanner → Cleanup policies: candidates evaluated (evidence: `README.md`)
- Cleanup policies → Safety validation: passes candidates (evidence: `README.md`)
- Safety validation → Ancestor checks: checks ancestry (evidence: `README.md`)
- Ancestor checks → Action planner: cleared for planning (evidence: `README.md`)
- Action planner → Fail-closed executor: supplies plan (evidence: `README.md`)
- CLI entry point → Fail-closed executor: executes plan (evidence: `cmd/storage-sage/main.go`)
- Fail-closed executor → Safety validation: revalidates before mutation (evidence: `internal/executor/simple.go`)
- Fail-closed executor → Soft-delete store: moves to trash (evidence: `internal/executor/simple.go`)
- Fail-closed executor → Audit trail: records result
- Daemon scheduler → CLI entry point: runs cleanup callback (evidence: `internal/daemon/daemon.go`)
- Administrator → Dashboard pages: views and manages (evidence: `README.md`)
- Dashboard pages → Data hooks: uses data hooks (evidence: `web/src/pages/Dashboard.tsx`)
- Dashboard pages → Dashboard components: renders controls (evidence: `web/src/pages/Dashboard.tsx`)
- Data hooks → HTTP API client: requests data (evidence: `web/src/hooks/useAuditHistory.ts`)
- HTTP API client → Daemon scheduler: calls HTTP endpoints (evidence: `web/src/api/client.ts`)
- Daemon scheduler → Audit trail: queries audit records (evidence: `internal/daemon/daemon.go`)
- Daemon scheduler → Soft-delete store: manages trash items (evidence: `internal/daemon/daemon.go`)
- Daemon scheduler → API authentication: protects API (evidence: `internal/daemon/daemon.go`)
- CLI entry point → Prometheus metrics: starts metrics service (evidence: `cmd/storage-sage/main.go`)
- Fail-closed executor → Prometheus metrics: records action metrics (evidence: `internal/executor/simple.go`)
- CLI entry point → Webhook notifications: configures notifications
- CLI entry point → Application logging: configures logging (evidence: `cmd/storage-sage/main.go`)