fin-hub/.claude/rules/architecture.md

## Architecture

Fin-hub extends `hub-core` with financial models and operator surfaces. Generic
hub primitives (domains, repos, messages, progress) come from hub-core;
fin-specific models and services live here.

### Modules

| Module | Role |
|--------|------|
| `models/` | Budget, commitment, service cost, burn rate dataclasses |
| `ingest/` | CSV parsers for cloud, Anthropic billing, HostEurope invoices |
| `services/runway.py` | Runway projection from balance + monthly burn series |
| `services/alerts.py` | Threshold evaluation (runway months, budget overrun) |
| `coupling/` | FOS §9 signals: fin→dev (resource pressure), fin→ops (cost attribution), fin→canon (viability) |
| `services/ledger.py` | SQLite cost ledger with monthly rollups |
| `services/evaluate.py` | Ledger-driven runway evaluation for cron |
| `services/evidence.py` | Non-secret dogfood evidence generation |
| `cli.py` | Operator CLI (`finhub` entrypoint) |

### Data flow

```
CSV exports → ingest parsers → cost models → runway/alerts → coupling emit → State Hub progress
```

v0.1 uses manual CSV import into a local SQLite ledger. HTTP read surface
remains deferred (`FIN-WP-0001-T06`).

## Quick Reference

`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference