# mamguitar2/tidylocal architecture

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

- Interactive diagram: https://gitdiagram.com/mamguitar2/tidylocal
- Repository: https://github.com/mamguitar2/tidylocal

## Overview

TidyLocal is a local-only macOS file review and organization app. The user selects approved locations and starts a read-only scan; the dashboard presents storage, file-age, and exact-duplicate findings, while Organize offers conservative suggestions and requires a separate confirmation for each action. The API coordinates scanning and guarded filesystem operations, with activity logging and identity-checked undo. The README documents optional app inventory and opt-in Ollama explanations; the sampled source confirms their modules, but not all route wiring, so those links are documented or marked optional.

Main entry points: [`app.py`](https://github.com/mamguitar2/tidylocal/blob/main/app.py) (Local API), [`static/app.js`](https://github.com/mamguitar2/tidylocal/blob/main/static/app.js) (Dashboard UI), [`undo.py`](https://github.com/mamguitar2/tidylocal/blob/main/undo.py) (Move and folder undo), [`operations.py`](https://github.com/mamguitar2/tidylocal/blob/main/operations.py) (Guarded filesystem actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Local interface"]
  node_launcher["Local launcher<br/>[launch.py]"]
  node_webapp["Dashboard page<br/>[index.html]"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
  node_charts["Review charts<br/>[charts.js]"]
  node_duplicate_ui["Duplicates and age UI<br/>[duplicates.js]"]
  node_organize_ui["Organize review UI<br/>[organize-ui.js]"]
end

subgraph group_review["Scan and review"]
  node_api["Local API<br/>[app.py]"]
  node_scanner["Approved-location scanner<br/>[scanner.py]"]
  node_classifier["Suggestion and text classifier<br/>[organizer.py]"]
end

subgraph group_actions["Safe file actions"]
  node_actions["Guarded filesystem actions<br/>[operations.py]"]
  node_undo["Move and folder undo<br/>[undo.py]"]
  node_activity[("Local activity log")]
end

subgraph group_integrations["Local integrations"]
  node_app_inventory["macOS app inventory<br/>[applications.py]"]
  node_ollama_helper["Opt-in explanation helper<br/>[ollama_local.py]"]
  node_ollama_service["Loopback Ollama"]
end

node_user(("Mac user"))

node_user -->|"launches"| node_launcher
node_launcher -->|"starts server"| node_api
node_user -->|"reviews"| node_dashboard
node_webapp -.->|"hosts interface"| node_dashboard
node_dashboard -->|"requests scans"| node_api
node_dashboard -->|"renders charts"| node_charts
node_duplicate_ui -->|"requests file actions"| node_api
node_organize_ui -.->|"requests organizing"| node_api
node_api -->|"starts scan"| node_scanner
node_scanner -->|"uses file descriptions"| node_classifier
node_api -.->|"requests suggestions"| node_classifier
node_api -->|"executes actions"| node_actions
node_actions -->|"resolves folders"| node_classifier
node_api -->|"requests undo"| node_undo
node_undo -->|"restores moves"| node_actions
node_api -->|"reads and logs"| node_activity
node_undo -->|"reads and logs"| node_activity
node_api -.->|"lists applications"| node_app_inventory
node_api -->|"requests explanations"| node_ollama_helper
node_ollama_helper -.->|"posts metadata"| node_ollama_service

click node_launcher "https://github.com/mamguitar2/tidylocal/blob/main/launch.py"
click node_webapp "https://github.com/mamguitar2/tidylocal/blob/main/templates/index.html"
click node_dashboard "https://github.com/mamguitar2/tidylocal/blob/main/static/app.js"
click node_charts "https://github.com/mamguitar2/tidylocal/blob/main/static/charts.js"
click node_duplicate_ui "https://github.com/mamguitar2/tidylocal/blob/main/static/duplicates.js"
click node_organize_ui "https://github.com/mamguitar2/tidylocal/blob/main/static/organize-ui.js"
click node_api "https://github.com/mamguitar2/tidylocal/blob/main/app.py"
click node_scanner "https://github.com/mamguitar2/tidylocal/blob/main/scanner.py"
click node_classifier "https://github.com/mamguitar2/tidylocal/blob/main/organizer.py"
click node_actions "https://github.com/mamguitar2/tidylocal/blob/main/operations.py"
click node_undo "https://github.com/mamguitar2/tidylocal/blob/main/undo.py"
click node_app_inventory "https://github.com/mamguitar2/tidylocal/blob/main/applications.py"
click node_ollama_helper "https://github.com/mamguitar2/tidylocal/blob/main/ollama_local.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_launcher,node_webapp,node_dashboard,node_charts,node_duplicate_ui,node_organize_ui,node_user toneBlue
class node_api,node_scanner,node_classifier toneAmber
class node_actions,node_undo,node_activity toneMint
class node_app_inventory,node_ollama_helper,node_ollama_service toneRose
```

## Components

### Local interface

- [Local launcher](https://github.com/mamguitar2/tidylocal/blob/main/launch.py): `launch.py`
- [Dashboard page](https://github.com/mamguitar2/tidylocal/blob/main/templates/index.html): `templates/index.html`
- [Dashboard UI](https://github.com/mamguitar2/tidylocal/blob/main/static/app.js): `static/app.js`
- [Review charts](https://github.com/mamguitar2/tidylocal/blob/main/static/charts.js): `static/charts.js`
- [Duplicates and age UI](https://github.com/mamguitar2/tidylocal/blob/main/static/duplicates.js): `static/duplicates.js`
- [Organize review UI](https://github.com/mamguitar2/tidylocal/blob/main/static/organize-ui.js): `static/organize-ui.js`

### Scan and review

- [Local API](https://github.com/mamguitar2/tidylocal/blob/main/app.py): `app.py`
- [Approved-location scanner](https://github.com/mamguitar2/tidylocal/blob/main/scanner.py): `scanner.py`
- [Suggestion and text classifier](https://github.com/mamguitar2/tidylocal/blob/main/organizer.py): `organizer.py`

### Safe file actions

- [Guarded filesystem actions](https://github.com/mamguitar2/tidylocal/blob/main/operations.py): `operations.py`
- [Move and folder undo](https://github.com/mamguitar2/tidylocal/blob/main/undo.py): `undo.py`
- **Local activity log**

### Local integrations

- [macOS app inventory](https://github.com/mamguitar2/tidylocal/blob/main/applications.py): `applications.py`
- [Opt-in explanation helper](https://github.com/mamguitar2/tidylocal/blob/main/ollama_local.py): `ollama_local.py`
- **Loopback Ollama**

### Other components

- **Mac user**

## Connections

- Mac user → Local launcher: launches (evidence: `README.md`)
- Local launcher → Local API: starts server (evidence: `launch.py`)
- Mac user → Dashboard UI: reviews (evidence: `README.md`)
- Dashboard page → Dashboard UI: hosts interface (evidence: `README.md`)
- Dashboard UI → Local API: requests scans (evidence: `static/app.js`)
- Dashboard UI → Review charts: renders charts
- Duplicates and age UI → Local API: requests file actions (evidence: `static/duplicates.js`)
- Organize review UI → Local API: requests organizing (evidence: `README.md`)
- Local API → Approved-location scanner: starts scan (evidence: `app.py`)
- Approved-location scanner → Suggestion and text classifier: uses file descriptions (evidence: `scanner.py`)
- Local API → Suggestion and text classifier: requests suggestions (evidence: `README.md`)
- Local API → Guarded filesystem actions: executes actions (evidence: `app.py`)
- Guarded filesystem actions → Suggestion and text classifier: resolves folders (evidence: `operations.py`)
- Local API → Move and folder undo: requests undo (evidence: `app.py`)
- Move and folder undo → Guarded filesystem actions: restores moves (evidence: `undo.py`)
- Local API → Local activity log: reads and logs (evidence: `app.py`)
- Move and folder undo → Local activity log: reads and logs (evidence: `undo.py`)
- Local API → macOS app inventory: lists applications (evidence: `README.md`)
- Local API → Opt-in explanation helper: requests explanations (evidence: `app.py`)
- Opt-in explanation helper → Loopback Ollama: posts metadata (evidence: `ollama_local.py`)