# jimzical/vizdisk architecture

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

- Interactive diagram: https://gitdiagram.com/jimzical/vizdisk
- Repository: https://github.com/jimzical/vizdisk

## Overview

1. **What the repo is**
   VizDisk is a single-purpose Go application that scans disk usage with `ncdu` and presents the results in a browser as an interactive treemap plus a list view. The core architecture is a small backend that orchestrates scanning and a bundled frontend that renders the results.

2. **Main runtime entrypoint**
   `main.go` is the top-level launcher. It likely coordinates three responsibilities: determine the target path to scan, invoke the scan/parse pipeline, and start the HTTP server. The README shows it also opens the browser automatically after startup.

3. **Scan subsystem**
   The scan engine is external: VizDisk depends on `ncdu` to traverse the filesystem efficiently. The app does not implement its own filesystem crawler; instead it shells out to `ncdu`, which makes disk scanning the primary boundary between VizDisk and the host OS/filesystem.

4. **Parsing subsystem**
   `internal/vizdisk/parser.go` is the translation layer from `ncdu`’s output into VizDisk’s internal tree model. This is the key data-shaping step: raw scan data is converted into a hierarchical structure with sizes that the UI can consume for both treemap and list rendering.

5. **HTTP server subsystem**
   `internal/vizdisk/server.go` hosts the web application. It serves the static frontend assets and likely exposes the parsed disk tree as the payload the browser uses. The server port is configurable via `NCDU_PORT`, with a default of `8810`.

6. **Browser automation**
   `internal/vizdisk/browser.go` encapsulates launching the system browser after the server starts. This is a convenience layer, separate from the server itself, so the app can run headless on a server or open locally when launched from a desktop.

7. **Frontend subsystem**
   `internal/vizdisk/index.html`, `style.css`, and `app.js` form the entire client UI. The frontend is a static D3.js-based visualization that consumes the tree data, renders the treemap/list views, and supports interactive exploration such as zooming into directories.

8. **Data flow through the system**
   The end-to-end path is: filesystem path chosen at startup → `ncdu` scans the mounted directory tree → parser converts scan output into a hierarchical model → HTTP server exposes that model and static assets → browser loads the page and `app.js` renders the visualization. The main architectural split is therefore “scan/parse on the backend” versus “render/interact in the browser.”

9. **Deployment shape**
   The README and Dockerfiles show the app is intended to run both as a local binary and as a container. In Docker, the scan target is mounted at `/scan`, and the container exposes the web UI on the configured port. This makes filesystem access an externalized runtime dependency.

10. **Build and release pipeline**
   The repo is designed for static/single-binary distribution. `go.mod`/`go.sum` define the Go module, `.goreleaser.yaml` and `.github/workflows/release.yml` drive release artifacts, and `Dockerfile.release` supports publishing a container image. `ci.yml` indicates automated validation on pull requests/commits.

11. **Architecture boundaries to draw**
   For a diagram, the main boundaries are: host filesystem and `ncdu` at the bottom; VizDisk backend in the middle; browser UI at the top. Inside the backend, separate scan execution, parsing, and HTTP serving. Inside the frontend, separate static asset delivery from client-side visualization logic.

12. **Operational constraints**
   VizDisk needs `ncdu` available on the host or inside the container, and it assumes read access to the mounted directory tree. The app is intentionally lightweight: it does not depend on a database, background worker, or external network service beyond the local browser connection.

Main entry points: [`internal/vizdisk/server.go`](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/server.go) (Server), [`main.go`](https://github.com/jimzical/vizdisk/blob/main/main.go) (Launcher), [`internal/vizdisk/parser.go`](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/parser.go) (Parser), [`internal/vizdisk/index.html`](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/index.html) (Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Launcher<br/>Go entrypoint<br/>[main.go]"]
  node_fs[("Filesystem<br/>host path")]
  node_ncdu{{"ncdu<br/>external scanner"}}
  node_parser["Parser<br/>tree mapper<br/>[parser.go]"]
  node_server["Server<br/>HTTP host<br/>[server.go]"]
  node_browser["Browser open<br/>desktop helper<br/>[browser.go]"]
end

subgraph group_frontend["Frontend"]
  node_html["Shell<br/>static page<br/>[index.html]"]
  node_app["Visualizer<br/>client app<br/>[app.js]"]
  node_style["Styles<br/>CSS<br/>[style.css]"]
end

subgraph group_delivery["Delivery"]
  node_docker["Container<br/>runtime image<br/>[Dockerfile.release]"]
  node_ci["CI<br/>workflow<br/>[ci.yml]"]
  node_release["Release<br/>workflow<br/>[release.yml]"]
end

node_main -->|"runs"| node_ncdu
node_ncdu -->|"reads"| node_fs
node_main -->|"feeds"| node_parser
node_parser -->|"data"| node_server
node_main -->|"starts"| node_server
node_server -->|"serves"| node_html
node_server -->|"api"| node_app
node_server -->|"serves"| node_style
node_html -->|"loads"| node_app
node_app -->|"renders"| node_parser
node_main -->|"opens"| node_browser
node_browser -->|"navigates"| node_html
node_docker -->|"packages"| node_server
node_ci -.->|"checks"| node_main
node_release -.->|"publishes"| node_docker

click node_main "https://github.com/jimzical/vizdisk/blob/main/main.go"
click node_parser "https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/parser.go"
click node_server "https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/server.go"
click node_browser "https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/browser.go"
click node_html "https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/index.html"
click node_app "https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/app.js"
click node_style "https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/style.css"
click node_docker "https://github.com/jimzical/vizdisk/blob/main/Dockerfile.release"
click node_ci "https://github.com/jimzical/vizdisk/blob/main/.github/workflows/ci.yml"
click node_release "https://github.com/jimzical/vizdisk/blob/main/.github/workflows/release.yml"

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_main,node_fs,node_ncdu,node_parser,node_server,node_browser toneBlue
class node_html,node_app,node_style toneAmber
class node_docker,node_ci,node_release toneMint
```

## Components

### Runtime

Local scan, parse, and serve path

- [Launcher](https://github.com/jimzical/vizdisk/blob/main/main.go): Go entrypoint · Starts the scan, server, and browser flow · `main.go`
- **Filesystem**: host path · Mounted directory being scanned
- **ncdu**: external scanner · External disk traversal and size collection tool
- [Parser](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/parser.go): tree mapper · Converts ncdu output into VizDisk's hierarchical model · `internal/vizdisk/parser.go`
- [Server](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/server.go): HTTP host · Serves the app and the parsed disk data · `internal/vizdisk/server.go`
- [Browser open](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/browser.go): desktop helper · Launches the system browser after startup · `internal/vizdisk/browser.go`

### Frontend

Static browser UI

- [Shell](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/index.html): static page · Application entry HTML served to the browser · `internal/vizdisk/index.html`
- [Visualizer](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/app.js): client app · Renders treemap and list views with interaction · `internal/vizdisk/app.js`
- [Styles](https://github.com/jimzical/vizdisk/blob/main/internal/vizdisk/style.css): CSS · Presentation layer for the browser UI · `internal/vizdisk/style.css`

### Delivery

Container and release automation

- [Container](https://github.com/jimzical/vizdisk/blob/main/Dockerfile.release): runtime image · Containerized way to run VizDisk with mounted scans · `Dockerfile.release`
- [CI](https://github.com/jimzical/vizdisk/blob/main/.github/workflows/ci.yml): workflow · Automated validation on changes · `.github/workflows/ci.yml`
- [Release](https://github.com/jimzical/vizdisk/blob/main/.github/workflows/release.yml): workflow · Builds and publishes release artifacts · `.github/workflows/release.yml`

## Connections

- Launcher → ncdu: runs · Launches the external scanner
- ncdu → Filesystem: reads · Traverses the mounted directory tree
- Launcher → Parser: feeds · Passes scan output into the tree parser
- Parser → Server: data · Provides the hierarchical model to the HTTP layer
- Launcher → Server: starts · Brings up the web server
- Server → Shell: serves · Delivers the browser entry page
- Server → Visualizer: api · Exposes parsed data for client-side rendering
- Server → Styles: serves · Delivers static styling assets
- Shell → Visualizer: loads · Bootstraps the client application
- Visualizer → Parser: renders · Uses the tree-shaped data to draw views
- Launcher → Browser open: opens · Automatically launches the system browser
- Browser open → Shell: navigates · Opens the local web UI
- Container → Server: packages · Bundles the backend and static frontend for container use
- CI → Launcher: checks · Validates the Go application in automation
- Release → Container: publishes · Produces release artifacts including the container image
