How jimzical/vizdisk works
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: server.go Server · main.go Launcher · parser.go Parser · index.html Shell
Components 12
Runtime
Local scan, parse, and serve path
- Launcher · Starts the scan, server, and browser flow
main.go - Filesystem · Mounted directory being scanned
- ncdu · External disk traversal and size collection tool
- Parser · Converts ncdu output into VizDisk's hierarchical model
internal/vizdisk/parser.go - Server · Serves the app and the parsed disk data
internal/vizdisk/server.go - Browser open · Launches the system browser after startup
internal/vizdisk/browser.go
Frontend
Static browser UI
- Shell · Application entry HTML served to the browser
internal/vizdisk/index.html - Visualizer · Renders treemap and list views with interaction
internal/vizdisk/app.js - Styles · Presentation layer for the browser UI
internal/vizdisk/style.css
Connections 15
- 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