# mouatezmo/vibediff architecture

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

- Interactive diagram: https://gitdiagram.com/mouatezmo/vibediff
- Repository: https://github.com/mouatezmo/vibediff
- Video tour (about a minute): https://gitdiagram.com/mouatezmo/vibediff/video

## Overview

VibeDiff is a single-file terminal application for tracking project checkpoints and versioned snapshots. A user opens or registers a project, saves snapshots, then compares versions or restores a saved state. The README also documents automatic comparison on update, visual line and intra-line diffs, live search, text reports, and ripgrep-backed scanning. The excerpts show the managers and some storage, scanning, and viewer behavior; some wiring for unsampled operations is therefore left out.

Main entry points: [`vibediff.py`](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py) (Project manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Project workflow"]
  node_app["Application entry<br/>[vibediff.py]"]
  node_projects["Project manager<br/>[vibediff.py]"]
  node_terminal["Terminal UI<br/>[vibediff.py]"]
end

subgraph group_snapshot["Snapshot handling"]
  node_snapshots["Snapshot manager<br/>[vibediff.py]"]
  node_storage[("Snapshot storage<br/>[vibediff.py]")]
end

subgraph group_comparison["Comparison experience"]
  node_diffengine["Diff engine<br/>[vibediff.py]"]
  node_viewer["Visual diff viewer<br/>[vibediff.py]"]
  node_reports["Text report generator<br/>[vibediff.py]"]
end

subgraph group_runtime["Runtime services"]
  node_environment["Environment manager<br/>[vibediff.py]"]
  node_scanner["Project scanner<br/>[vibediff.py]"]
end

node_user(("Terminal user"))
node_ripgrep["ripgrep"]
node_projectfiles[("Project files")]

node_user -->|"runs"| node_app
node_app -->|"detects environment"| node_environment
node_app -->|"starts workflow"| node_projects
node_projects -->|"presents menus"| node_terminal
node_projects -->|"lists and reconciles"| node_storage
node_projects -->|"manages snapshots"| node_snapshots
node_snapshots -->|"scans source"| node_scanner
node_scanner -->|"reads files"| node_projectfiles
node_scanner -.->|"scans with"| node_ripgrep
node_snapshots -->|"saves snapshots"| node_storage
node_snapshots -->|"compares versions"| node_diffengine
node_diffengine -->|"reads snapshots"| node_storage
node_projects -->|"opens visual diff"| node_viewer
node_projects -->|"produces comparison report"| node_reports

click node_app "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_projects "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_environment "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_scanner "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_snapshots "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_storage "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_diffengine "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_viewer "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_reports "https://github.com/mouatezmo/vibediff/blob/main/vibediff.py"
click node_terminal "https://github.com/mouatezmo/vibediff/blob/main/vibediff.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_app,node_projects,node_terminal,node_user toneBlue
class node_snapshots,node_storage,node_projectfiles toneAmber
class node_diffengine,node_viewer,node_reports toneMint
class node_environment,node_scanner toneRose
class node_ripgrep toneIndigo
```

## Components

### Project workflow

- [Application entry](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`
- [Project manager](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`
- [Terminal UI](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`

### Snapshot handling

- [Snapshot manager](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`
- [Snapshot storage](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`

### Comparison experience

- [Diff engine](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`
- [Visual diff viewer](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`
- [Text report generator](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`

### Runtime services

- [Environment manager](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`
- [Project scanner](https://github.com/mouatezmo/vibediff/blob/main/vibediff.py): `vibediff.py`

### Other components

- **Terminal user**
- **ripgrep**
- **Project files**

## Connections

- Terminal user → Application entry: runs
- Application entry → Environment manager: detects environment
- Application entry → Project manager: starts workflow
- Project manager → Terminal UI: presents menus
- Project manager → Snapshot storage: lists and reconciles
- Project manager → Snapshot manager: manages snapshots
- Snapshot manager → Project scanner: scans source
- Project scanner → Project files: reads files
- Project scanner → ripgrep: scans with
- Snapshot manager → Snapshot storage: saves snapshots
- Snapshot manager → Diff engine: compares versions
- Diff engine → Snapshot storage: reads snapshots
- Project manager → Visual diff viewer: opens visual diff
- Project manager → Text report generator: produces comparison report