How siddhantac/puffin works
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