# hellotem/local_wandb architecture

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

- Interactive diagram: https://gitdiagram.com/hellotem/local_wandb
- Repository: https://github.com/hellotem/local_wandb

## Overview

##### Project type and purpose
- This is an open-source, offline experiment‐tracking tool (a lightweight local alternative to wandb.ai).

##### File structure
- Root directory:
- LICENSE, README.md
- local_wandb.py – core logging/IO library (write & read modes)
- local_wandb_ui.py – offline GUI entry point for visualizing experiments
- Runtime‐generated structure under `local_wandb/<project>/<run-timestamp-name>/`:
- config.json, metrics.csv
- images/ (PNG)
- tensors/ (NumPy .npy files)

##### README for architecture clues
- The README describes:
- A logging API that emits JSON, CSV, PNG, NPY to disk
- A list_runs & read‐mode API that reads existing runs
- A PyQt5 GUI that inputs run folders and renders plots, images, histograms

a. Main components
1. Client Code (user scripts that import LocalWandb)
2. Logging Library (local_wandb.py)
3. Local File System Storage (project/run folders: JSON, CSV, images/, tensors/)
4. Offline GUI Application (local_wandb_ui.py & internal visualization modules)
5. Third‐party Dependencies (PyQt5, Matplotlib, NumPy, (optional) PyTorch)

b. Relationships & data flows
- Client Code → Logging Library: calls run.config, run.log*, run.finish()
- Logging Library → File System: writes config.json, metrics.csv, .png, .npy
- GUI Application → File System: scans folder tree via LocalWandb.list_runs, reads files
- GUI Subcomponents (Plotter, Image Viewer, Tensor Histogram) ← File content
- GUI ←→ User: interactive selection, comparisons, plots

c. Architectural patterns & principles
- Layered architecture:
– API layer (Logging vs. Visualization)
– Storage layer (structured on‐disk)
- Separation of concerns: logging vs. UI
- Extensibility points: adding new log_* methods or visualization widgets
- Stateless library: all state persisted on disk, making it reproducible

d. Key technologies & libraries
- Python 3.x
- local_wandb.py: built‐in modules (json, csv, os), NumPy for tensors, Matplotlib for figure saving
- local_wandb_ui.py: PyQt5 GUI, Matplotlib (embedded), NumPy
- File formats: JSON (config), CSV (metrics), PNG (images/figures), NPY (tensors)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    UserScript["Client Code\n(User Experiment Scripts)"]:::external

    %% Logging Library Layer
    LoggingAPI["Logging Library\n(local_wandb.py)"]:::library
    click LoggingAPI "https://github.com/hellotem/local_wandb/blob/main/local_wandb.py"

    %% Dependencies
    subgraph "Third-Party Dependencies"
        direction TB
        PyQt5["PyQt5"]:::dependency
        Matplotlib["Matplotlib"]:::dependency
        NumPy["NumPy"]:::dependency
        PyTorch["PyTorch (optional)"]:::dependency
    end

    %% Storage Layer
    subgraph "Storage (Local File System)"
        direction TB
        Config["config.json"]:::storage
        Metrics["metrics.csv"]:::storage
        Images["images/*.png"]:::storage
        Tensors["tensors/*.npy"]:::storage
    end

    %% GUI Layer
    GUIApp["Offline GUI Application\n(local_wandb_ui.py)"]:::gui
    click GUIApp "https://github.com/hellotem/local_wandb/blob/main/local_wandb_ui.py"

    subgraph "Visualization Modules"
        direction TB
        Plotter["Plotter Module"]:::gui
        ImageViewer["Image Viewer"]:::gui
        TensorHist["Tensor Histogram"]:::gui
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        README["README.md\n(Project Architecture)"]:::doc
        click README "https://github.com/hellotem/local_wandb/blob/main/README.md"
        LICENSE["LICENSE\n(Third-Party Notes)"]:::doc
        click LICENSE "https://github.com/hellotem/local_wandb/tree/main/LICENSE"
    end

    %% User Interaction
    UserInterface["User Interface"]:::external

    %% Relationships
    UserScript -->|"import LocalWandb.run(), .log*, .finish()"| LoggingAPI
    LoggingAPI -->|"writes JSON"| Config
    LoggingAPI -->|"writes CSV"| Metrics
    LoggingAPI -->|"saves PNG"| Images
    LoggingAPI -->|"saves NPY"| Tensors

    GUIApp -->|"scans folders\nvia list_runs()"| Config
    GUIApp -->|"reads metrics"| Metrics
    GUIApp -->|"loads images"| Images
    GUIApp -->|"loads tensors"| Tensors

    GUIApp --> Plotter
    GUIApp --> ImageViewer
    GUIApp --> TensorHist

    Plotter -->|"renders plots"| UserInterface
    ImageViewer -->|"displays images"| UserInterface
    TensorHist -->|"shows histograms"| UserInterface

    README --> LoggingAPI
    README --> GUIApp
    LICENSE --> LoggingAPI

    %% Styles
    classDef library fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef gui fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef dependency fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px;
    classDef doc fill:#F5F5F5,stroke:#333,stroke-width:1px;
```
