lobo/zfin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 2 Wiki Activity Actions

update README

Browse source
This commit is contained in:
Emil Lerch 2026-06-26 17:01:37 -07:00
parent 0cd01dd452
commit 46375fed5a
Signed by: lobo
GPG key ID: A7B62D657EF764F8
1 changed files with 111 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

157
README.md
View file

@ -1,6 +1,6 @@
# zfin
A financial data library, CLI, and terminal UI written in Zig. Tracks portfolios, analyzes trailing returns, displays options chains, earnings history, and more -- all from the terminal.
A financial data library, CLI, and terminal UI written in Zig. Tracks portfolios, analyzes trailing returns, displays options chains and earnings history, and renders price and projection charts (inline Kitty graphics or PNG export) -- all from the terminal.
## Quick start
@ -102,60 +102,124 @@ caching/TTL model, and the complete environment-variable list, see
```
src/
root.zig Library root, exports all public types
format.zig Shared formatters, braille engine, ANSI helpers
config.zig Configuration from env vars / .env files
service.zig DataService: cache-check -> fetch -> cache -> return
main.zig CLI dispatch + TUI entry point
root.zig Library root, exports all public types
Config.zig Configuration from env vars / .env files
service.zig DataService: cache-check -> fetch -> cache -> return
Date.zig Date type (i32 days since epoch); arithmetic, formatting
Money.zig Money formatting ($1,234.56; whole/trim/signed variants)
format.zig Shared formatters, braille engine, ANSI helpers
padded.zig Generic width/alignment wrapper for any formattable type
PortfolioData.zig Per-portfolio parse, price fetch, summary, background workers
portfolio_loader.zig Loads + union-merges portfolio_*.srf for CLI and TUI
compare.zig Composes two points in time (snapshot vs live) for `compare`
history.zig Reads history/<date>-portfolio.srf snapshots; aggregation
market.zig Market calendar; close-anchored cache freshness
git.zig Thin git subprocess wrappers (diff/walk tracked portfolios)
atomic.zig Crash-safe atomic file writes (tmp + fsync + rename)
stderr.zig Best-effort (non-throwing) stderr hint/progress writers
term_graphics.zig Kitty graphics emission for plain (non-TUI) CLI charts
term_query.zig Terminal capability probing for inline CLI graphics
chart_export.zig Chart-to-PNG export (`--export-chart <path>`)
comptime_validator.zig Shared comptime contract-validation helpers
models/
candle.zig OHLCV price bars
date.zig Date type with arithmetic, snapping, formatting
dividend.zig Dividend records with type classification
split.zig Stock splits
option.zig Option contracts and chains
earnings.zig Earnings events with surprise calculation
etf_profile.zig ETF profiles with holdings and sectors
portfolio.zig Lots, positions, and portfolio aggregation
classification.zig Classification metadata parser
quote.zig Real-time quote data
candle.zig OHLCV price bars
quote.zig Real-time quote data
dividend.zig Dividend records with type classification
split.zig Stock splits
option.zig Option contracts and chains
earnings.zig Earnings events with surprise calculation
etf_profile.zig ETF profiles with holdings and sectors
portfolio.zig Lots, positions, and portfolio aggregation
classification.zig Classification metadata parser
snapshot.zig Snapshot record types (history/*-portfolio.srf wire format)
transaction_log.zig transaction_log.srf wire format (transfer:: records)
shiller_year.zig One year of Shiller returns (S&P / bond / CPI)
providers/
tiingo.zig Tiingo: daily candles (primary), supplementary div/split merge
twelvedata.zig TwelveData: quote fallback
polygon.zig Polygon: dividends, splits (primary, with forward-looking entries)
fmp.zig FMP: earnings (actuals + estimates)
cboe.zig CBOE: options chains (no API key)
Edgar.zig SEC EDGAR: ETF profiles (NPORT-P), mutual-fund ticker map, XBRL company facts
Wikidata.zig Wikidata SPARQL: classification metadata for `enrich`
yahoo.zig Yahoo Finance: quotes (primary), candles (Tiingo fallback)
openfigi.zig OpenFIGI: CUSIP to ticker lookup
xml.zig Vendored XML parser used by Edgar.zig (see "Vendored code")
tiingo.zig Tiingo: daily candles (primary)
yahoo.zig Yahoo Finance: quotes (primary), candle fallback
twelvedata.zig TwelveData: quote fallback
polygon.zig Polygon: dividends, splits (with forward-looking entries)
fmp.zig FMP: earnings (actuals + estimates)
cboe.zig CBOE: options chains (no API key)
Edgar.zig SEC EDGAR: ETF profiles (NPORT-P), ticker map, XBRL facts
Wikidata.zig Wikidata SPARQL: classification metadata for `enrich`
openfigi.zig OpenFIGI: CUSIP to ticker lookup
json_utils.zig Shared JSON parsing helpers
xml.zig Vendored XML parser used by Edgar.zig (see "Vendored code")
analytics/
indicators.zig SMA, Bollinger Bands, RSI
performance.zig Trailing returns (as-of-date + month-end)
risk.zig Volatility, Sharpe, drawdown
valuation.zig Portfolio summary, allocations, covered call adjustments
analysis.zig Portfolio analysis engine (breakdowns by class/sector/geo/account/tax)
indicators.zig SMA, Bollinger Bands, RSI
performance.zig Trailing returns (as-of-date + month-end)
risk.zig Per-symbol volatility, Sharpe, drawdown
portfolio_risk.zig Correlation-aware portfolio-level risk
valuation.zig Portfolio summary, allocations, covered-call adjustments
analysis.zig Breakdowns by class/sector/geo/account/tax
benchmark.zig Per-position benchmark returns
exposure.zig Look-through exposure (direct + ETF holdings)
milestones.zig Retirement-attainment grid
projections.zig Monte Carlo + percentile bands
forecast_evaluation.zig Forecast-vs-actual (convergence + return back-test)
observations.zig Portfolio sanity checks for the review surface
timeline.zig History-tab tier rollup
data/
ie_data.csv Raw Shiller S&P 500 + CPI dataset (CSV)
shiller.zig Shiller series, comptime-generated from ie_data.csv
imported_values.zig Back-history portfolio values (imported from spreadsheet)
staleness.zig Account-cadence staleness checks
Journal.zig acknowledgments.srf journal (acknowledged findings)
brokerage/
types.zig Normalized BrokeragePosition record + dollar parser
fidelity.zig Fidelity "Download Positions" CSV parser
schwab.zig Schwab export parser
wells_fargo.zig Wells Fargo export parser
views/
portfolio_sections.zig Portfolio view model (renderer-agnostic StyleIntent)
compare.zig Compare view model
history.zig History view model
projections.zig Projections view model
review.zig Per-holding performance + risk dashboard view model
observations_view.zig Findings list (engine output + acknowledgments)
cache/
store.zig SRF file cache with TTL freshness checks
net/
http.zig HTTP client with retries and server error retry
rate_limiter.zig Token-bucket rate limiter
store.zig SRF file cache with TTL freshness checks
net/
http.zig HTTP client with retries and server-error retry
RateLimiter.zig Token-bucket rate limiter
commands/
common.zig Shared CLI helpers (progress, formatting)
perf.zig Trailing returns command
quote.zig Quote command
... (14 command files)
tui.zig Interactive TUI application
common.zig Shared CLI helpers (progress, formatting, color)
framework.zig CLI command framework + portfolio pattern resolution
TimeRange.zig Shared --range / time-window parsing
audit/ Brokerage reconciliation helpers for `audit`
(one .zig per CLI command: perf, quote, portfolio, analysis, history, ...)
charts/
chart.zig Price + Bollinger + volume + RSI renderer (z2d)
projection_chart.zig Percentile-band + median projection renderer
forecast_chart.zig Convergence / back-test line renderer
line_chart.zig Single-series value-over-time line renderer
axis.zig Shared axis-label helpers
draw.zig Shared z2d drawing primitives
text.zig 5x7 bitmap font for axis labels
tui.zig Interactive TUI App orchestrator
tui/
chart.zig z2d pixel chart renderer (Kitty graphics)
keybinds.zig Configurable keybinding system
theme.zig Configurable color theme
tab_framework.zig Tab contract + comptime validator
keybinds.zig Configurable keybinding system
theme.zig Configurable color theme
input_buffer.zig Modal text-input state machine
(nine *_tab.zig tabs: portfolio, analysis, review, projections,
history, quote, performance, earnings, options)
version.zig Build version string
```
Data files (user-managed, in project root):
Data files (user-managed, auto-detected in cwd or `$ZFIN_HOME`):
```
portfolio.srf Portfolio lots
metadata.srf Classification metadata for analysis
accounts.srf Account to tax type mapping for analysis
portfolio.srf Portfolio lots (positions and cost basis)
accounts.srf Account -> tax-type mapping for analysis
metadata.srf Per-symbol classification (class/sector/geo) for analysis
watchlist.srf Symbols to track in the TUI watchlist
transaction_log.srf Declared transfers so contributions math skips internal moves
projections.srf Retirement / Monte Carlo projection assumptions
theme.srf TUI color theme overrides
keys.srf TUI keybinding overrides
acknowledgments.srf Acknowledged review-tab findings (app-maintained)
```
### Dependencies
@ -165,6 +229,7 @@ accounts.srf Account to tax type mapping for analysis
| [SRF](https://git.lerch.org/lobo/srf) | Git | Cache file format and portfolio/watchlist parsing |
| [libvaxis](https://github.com/rockorager/libvaxis) | Git (v0.6.0) | Terminal UI rendering |
| [z2d](https://github.com/vancluever/z2d) | Git (v0.11.0) | Pixel chart rendering (Kitty graphics protocol) |
| [zeit](https://github.com/rockorager/zeit) | Git (v0.9.0) | Calendar arithmetic + timezone conversion (ET) |
## Building