# siddhantac/puffin architecture

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

- Interactive diagram: https://gitdiagram.com/siddhantac/puffin
- Repository: https://github.com/siddhantac/puffin

## Overview

##### Project type and purpose
- Puffin is a single‐binary, full‐stack CLI application written in Go. It presents an interactive terminal dashboard for personal finance by running hledger commands under the hood and rendering the results via the Bubble Tea TEA (The Elm Architecture) UI framework.

##### File structure
- Top level
- main.go – entry point, parses flags (e.g., “-v3”), loads config, kicks off the UI
- config.json / config.debug.json – optional JSON config for report definitions
- data/ – sample journal and CSV data for demos
- assets/ – static demo GIF and keybinding screenshot
- ui/ – core UI code (model, view, update, styles)
- ui/v2/ – redesigned UI components, caching, new command runner, interfaces
- CI/CD
- .github/workflows – Go test/build and goreleaser jobs
- Makefile / goreleaser.yaml – build orchestration
- Tests
- ui/data_transformer_test.go

##### README for additional insights
- Purpose: surf hledger reports (balance, register, income statement, etc.)
- V3 revamps UI but still follows same high-level flow: run hledger → parse output → render in terminal
- Configuration: custom “reports” array (name, cmd, locked flag)

##### Main components and interactions (
a. Components
1. CLI Entrypoint (main.go)
2. Config Loader (reads JSON, applies defaults)
3. Hledger Runner (executes shell commands)
4. Data Transformer (parses CSV / plain text into Go structs)
5. UI Controller (Bubble Tea TEA loop: Model, Update, View)
6. UI Views (tables, graphs, tabs in ui/ and ui/v2/)
7. Cache Layer (ui/v2/cache) for expensive commands in V3
8. External Dependencies (hledger binary, terminal)
b. Relationships & Data Flow
- User invokes CLI → CLI Entrypoint
- Entrypoint loads Config → initializes UI Controller
- UI fetches data by calling Hledger Runner → returns raw output
- Raw output → Data Transformer → Go data models
- UI Controller (Update) receives data models → triggers View render
- View produces styled terminal output → Terminal
- User keystrokes flow back into UI Controller → may trigger new Hledger Runner calls or local state updates
c. Architectural patterns / principles
- Unidirectional data flow (TEA: Model → Update → View → Render → new Model)
- Separation of concerns:
– Config & CLI logic decoupled from UI
– Data parsing isolated in ui/data_transformer.go
– UI rendering abstracted behind Bubble Tea interfaces
- Extensibility:
– JSON‐driven “reports” allow plug-and-play of new hledger commands
– ui/v2/interfaces defines contracts for new UI components
d. Key technologies / libraries
- Go modules (go.mod)
- Bubble Tea (terminal UI framework)
- Lip Gloss (styling)
- hledger (finance engine)
- Go’s exec package (run shell commands)

##### Essential details to capture
- The TEA pattern’s unidirectional flow—no circular coupling
- Separation of config, runner, transformer, UI logic
- V3 cache shortcut to avoid re‐invoking hledger on each interaction
- External dependency on the hledger CLI
- Use of Go’s exec and CSV parsing libraries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    subgraph "User Interaction"
        User[(User / Terminal)]:::external
    end
    User -->|"invoke CLI"| CLIEntrypoint["CLI Entrypoint"]:::core

    %% Core Application Flow
    CLIEntrypoint -->|"load JSON Config"| ConfigLoader["Config Loader"]:::config
    ConfigLoader -->|"init TEA Loop"| UIController["UI Controller (Model/Update/View)"]:::core

    %% Data Fetch Flow V1
    UIController -->|"request data"| HledgerRunner1["Hledger Runner (v1)"]:::process
    HledgerRunner1 -->|"Shell stdout"| DataTransformer["Data Transformer"]:::core
    DataTransformer -->|"Go Structs"| UIController

    %% Data Fetch Flow V2 with Cache
    UIController -->|"request data"| CacheLayer["v2 Cache Layer"]:::core
    CacheLayer -->|cache miss| HledgerRunner2["Hledger Runner (v2)"]:::process
    CacheLayer -->|cache hit| DataTransformer
    HledgerRunner2 -->|"Shell stdout"| DataTransformer

    %% Rendering and Interaction
    UIController -->|"render"| TerminalOutput["Terminal Output"]:::ui
    TerminalOutput -->|"user input │ Tea Msgs"| UIController

    %% UI Views v1
    subgraph "UI Views v1" 
        MainView["main_view.go"] 
        SettingsView["settings_view.go"]
        Header["header.go"]
        Help["help.go"]
        Pager["pager.go"]
        Table["table.go"]
        TableGraph["table_graph.go"]
        Tabs["tabs.go"]
        FilterGroup["filterGroup.go"]
        Spinner["spinner.go"]
        Style["style.go"]
        Theme["theme.go"]
    end
    UIController --> MainView
    UIController --> SettingsView
    UIController --> Header
    UIController --> Help
    UIController --> Pager
    UIController --> Table
    UIController --> TableGraph
    UIController --> Tabs
    UIController --> FilterGroup
    UIController --> Spinner
    UIController --> Style
    UIController --> Theme

    %% UI Components & Interfaces v2
    subgraph "UI Components & Interfaces (v2)"
        V2UI["ui.go"]
        Home["home.go"]
        ComplexTable["complex_table.go"]
        Divider["divider.go"]
        Filter["filter.go"]
        DisplayOption["display_option.go"]
        V2Spinner["spinner.go"]
        V2Tabs["tabs.go"]
        V2Styles["styles.go"]
        Commands["commands.go"]
        Reports["reports.go"]
        Interfaces["interfaces.go"]
    end
    UIController --> V2UI
    UIController --> Home
    UIController --> ComplexTable
    UIController --> Divider
    UIController --> Filter
    UIController --> DisplayOption
    UIController --> V2Spinner
    UIController --> V2Tabs
    UIController --> V2Styles
    UIController --> Commands
    UIController --> Reports
    UIController --> Interfaces

    %% CI/CD & Build
    subgraph "CI/CD & Build"
        Workflows1[".github/workflows/go.yml"] 
        Workflows2[".github/workflows/goreleaser.yml"]
        Makefile["Makefile"]
        GoreleaserConfig[".goreleaser.yaml"]
    end
    CLIEntrypoint --> Workflows1
    CLIEntrypoint --> Workflows2
    CLIEntrypoint --> Makefile
    CLIEntrypoint --> GoreleaserConfig

    %% Sample Data & Assets
    subgraph "Sample Data & Assets"
        Journal["hledger.journal"]
        IncomeCSV["incomestmt.csv"]
        IncomeYearly["incomestmt_yearly.csv"]
        AssetsDir["assets/"]
    end
    ConfigLoader --> Journal
    ConfigLoader --> IncomeCSV
    ConfigLoader --> IncomeYearly
    ConfigLoader --> AssetsDir

    %% Class Definitions
    classDef core fill:#AED6F1,stroke:#1F618D,color:#1F618D;
    classDef process fill:#F5B041,stroke:#A04000,color:#A04000;
    classDef config fill:#ABEBC6,stroke:#196F3D,color:#196F3D;
    classDef ui fill:#D2B4DE,stroke:#512E5F,color:#512E5F;
    classDef external fill:#FAD7A0,stroke:#B9770E,color:#B9770E;

    %% Click Events
    click CLIEntrypoint "https://github.com/siddhantac/puffin/blob/main/main.go"
    click ConfigLoader "https://github.com/siddhantac/puffin/blob/main/ui/config.go"
    click Journal "https://github.com/siddhantac/puffin/blob/main/data/hledger.journal"
    click IncomeCSV "https://github.com/siddhantac/puffin/blob/main/data/incomestmt.csv"
    click IncomeYearly "https://github.com/siddhantac/puffin/blob/main/data/incomestmt_yearly.csv"
    click AssetsDir "https://github.com/siddhantac/puffin/tree/main/assets/"
    click HledgerRunner1 "https://github.com/siddhantac/puffin/blob/main/ui/command.go"
    click HledgerRunner2 "https://github.com/siddhantac/puffin/blob/main/ui/v2/command_runner.go"
    click HledgerRunner2 "https://github.com/siddhantac/puffin/blob/main/ui/v2/hledger/hledger.go"
    click DataTransformer "https://github.com/siddhantac/puffin/blob/main/ui/data_transformer.go"
    click DataTransformer "https://github.com/siddhantac/puffin/blob/main/ui/parse_csv.go"
    click DataTransformer "https://github.com/siddhantac/puffin/blob/main/ui/data_transformer_test.go"
    click UIController "https://github.com/siddhantac/puffin/blob/main/ui/ui.go"
    click UIController "https://github.com/siddhantac/puffin/blob/main/ui/model.go"
    click UIController "https://github.com/siddhantac/puffin/blob/main/ui/content_model.go"
    click MainView "https://github.com/siddhantac/puffin/blob/main/ui/main_view.go"
    click SettingsView "https://github.com/siddhantac/puffin/blob/main/ui/settings_view.go"
    click Header "https://github.com/siddhantac/puffin/blob/main/ui/header.go"
    click Help "https://github.com/siddhantac/puffin/blob/main/ui/help.go"
    click Pager "https://github.com/siddhantac/puffin/blob/main/ui/pager.go"
    click Table "https://github.com/siddhantac/puffin/blob/main/ui/table.go"
    click TableGraph "https://github.com/siddhantac/puffin/blob/main/ui/table_graph.go"
    click Tabs "https://github.com/siddhantac/puffin/blob/main/ui/tabs.go"
    click FilterGroup "https://github.com/siddhantac/puffin/blob/main/ui/filterGroup.go"
    click Spinner "https://github.com/siddhantac/puffin/blob/main/ui/spinner.go"
    click Style "https://github.com/siddhantac/puffin/blob/main/ui/style.go"
    click Theme "https://github.com/siddhantac/puffin/blob/main/ui/theme.go"
    click V2UI "https://github.com/siddhantac/puffin/blob/main/ui/v2/ui.go"
    click Home "https://github.com/siddhantac/puffin/blob/main/ui/v2/home.go"
    click ComplexTable "https://github.com/siddhantac/puffin/blob/main/ui/v2/complex_table.go"
    click Divider "https://github.com/siddhantac/puffin/blob/main/ui/v2/divider.go"
    click Filter "https://github.com/siddhantac/puffin/blob/main/ui/v2/filter.go"
    click DisplayOption "https://github.com/siddhantac/puffin/blob/main/ui/v2/display_option.go"
    click V2Spinner "https://github.com/siddhantac/puffin/blob/main/ui/v2/spinner.go"
    click V2Tabs "https://github.com/siddhantac/puffin/blob/main/ui/v2/tabs.go"
    click V2Styles "https://github.com/siddhantac/puffin/blob/main/ui/v2/styles.go"
    click Commands "https://github.com/siddhantac/puffin/blob/main/ui/v2/commands.go"
    click Reports "https://github.com/siddhantac/puffin/blob/main/ui/v2/reports.go"
    click Interfaces "https://github.com/siddhantac/puffin/blob/main/ui/v2/interfaces/interfaces.go"
    click CacheLayer "https://github.com/siddhantac/puffin/blob/main/ui/v2/cache/cache.go"
    click Workflows1 "https://github.com/siddhantac/puffin/blob/main/.github/workflows/go.yml"
    click Workflows2 "https://github.com/siddhantac/puffin/blob/main/.github/workflows/goreleaser.yml"
    click Makefile "https://github.com/siddhantac/puffin/tree/main/Makefile"
    click GoreleaserConfig "https://github.com/siddhantac/puffin/blob/main/.goreleaser.yaml"
```
