# chncaesar/opencode-db-clean architecture

> Architecture diagram of the GitHub repository chncaesar/opencode-db-clean, 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/chncaesar/opencode-db-clean
- Repository: https://github.com/chncaesar/opencode-db-clean
- Video tour (about a minute): https://gitdiagram.com/chncaesar/opencode-db-clean/video

## Overview

ocdbc is a single-file command-line tool for inspecting and safely reclaiming space in OpenCode’s SQLite database. Users run `analyze` for a read-only storage report, or `vacuum` for a guarded maintenance sequence. The diagram separates those domain stages and the internal statistics/reporting layer while keeping the database, lock check, and backup visible. The README documents the full vacuum sequence; omitted source excerpts limit confirmation of its internal call wiring.

Main entry points: [`ocdbc.py`](https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py) (Safe maintenance steps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI commands"]
  node_cli["Command entry<br/>[ocdbc.py]"]
end

subgraph group_analysis["Analysis"]
  node_analyze["Analyze command<br/>[ocdbc.py]"]
  node_stats["Database statistics<br/>[ocdbc.py]"]
  node_report["Health report<br/>[ocdbc.py]"]
end

subgraph group_maintenance["Maintenance"]
  node_vacuum["Vacuum command<br/>[ocdbc.py]"]
  node_lock["Open-handle check<br/>[ocdbc.py]"]
  node_maintenance_steps["Safe maintenance steps<br/>[ocdbc.py]"]
end

node_user(("Operator"))
node_database[("OpenCode SQLite DB")]
node_fuser["fuser utility"]
node_backup["Timestamped backup"]

node_user -->|"runs command"| node_cli
node_cli -->|"dispatches analyze"| node_analyze
node_cli -->|"dispatches vacuum"| node_vacuum
node_analyze -->|"collects stats"| node_stats
node_stats -->|"reads metadata"| node_database
node_stats -->|"queries tables"| node_database
node_analyze -->|"renders report"| node_report
node_stats -->|"supplies stats"| node_report
node_vacuum -->|"checks handle"| node_lock
node_lock -->|"invokes"| node_fuser
node_vacuum -->|"collects before stats"| node_stats
node_vacuum -->|"runs sequence"| node_maintenance_steps
node_maintenance_steps -->|"checkpoints WAL"| node_database
node_maintenance_steps -->|"checks integrity"| node_database
node_maintenance_steps -->|"creates and verifies"| node_backup
node_maintenance_steps -->|"sets auto-vacuum"| node_database
node_maintenance_steps -->|"vacuums and restores WAL"| node_database

click node_cli "https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py"
click node_analyze "https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py"
click node_stats "https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py"
click node_report "https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py"
click node_vacuum "https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py"
click node_lock "https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py"
click node_maintenance_steps "https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py"

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_fuser toneBlue
class node_analyze,node_stats,node_report,node_database toneAmber
class node_vacuum,node_lock,node_maintenance_steps toneMint
class node_user,node_backup toneIndigo
```

## Components

### CLI commands

- [Command entry](https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py): `ocdbc.py`

### Analysis

- [Analyze command](https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py): `ocdbc.py`
- [Database statistics](https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py): `ocdbc.py`
- [Health report](https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py): `ocdbc.py`

### Maintenance

- [Vacuum command](https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py): `ocdbc.py`
- [Open-handle check](https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py): `ocdbc.py`
- [Safe maintenance steps](https://github.com/chncaesar/opencode-db-clean/blob/master/ocdbc.py): `ocdbc.py`

### Other components

- **Operator**
- **OpenCode SQLite DB**
- **fuser utility**
- **Timestamped backup**

## Connections

- Operator → Command entry: runs command
- Command entry → Analyze command: dispatches analyze
- Command entry → Vacuum command: dispatches vacuum
- Analyze command → Database statistics: collects stats
- Database statistics → OpenCode SQLite DB: reads metadata
- Database statistics → OpenCode SQLite DB: queries tables
- Analyze command → Health report: renders report
- Database statistics → Health report: supplies stats
- Vacuum command → Open-handle check: checks handle
- Open-handle check → fuser utility: invokes
- Vacuum command → Database statistics: collects before stats
- Vacuum command → Safe maintenance steps: runs sequence
- Safe maintenance steps → OpenCode SQLite DB: checkpoints WAL
- Safe maintenance steps → OpenCode SQLite DB: checks integrity
- Safe maintenance steps → Timestamped backup: creates and verifies
- Safe maintenance steps → OpenCode SQLite DB: sets auto-vacuum
- Safe maintenance steps → OpenCode SQLite DB: vacuums and restores WAL