# Finance System v0.5 Repo Blueprint / Implementation Plan

Updated 2026-05-14.

v0.5 prepares concrete MVP 1 implementation. It is not a new feature wishlist.

## Repo layout

Repo: `jarvis-finance-system`.

Core folders:
- `src/jarvis_finance/config/`
- `src/jarvis_finance/storage/`
- `src/jarvis_finance/models/`
- `src/jarvis_finance/ledger/`
- `src/jarvis_finance/crypto/`
- `src/jarvis_finance/imports/`
- `src/jarvis_finance/market_data/`
- `src/jarvis_finance/fx/`
- `src/jarvis_finance/dashboard/`
- `src/jarvis_finance/reports/`
- `src/jarvis_finance/audit/`
- `src/jarvis_finance/quality/`
- `src/jarvis_finance/cli/`
- `tests/unit/`, `tests/integration/`, `tests/fixtures/`
- `examples/synthetic/`
- `docs/architecture/`, `docs/decisions/`, `docs/plans/`
- `config.example/`

## Runtime layout

Production runtime defaults outside repo:
- `~/jarvis_runtime/finance-system/data/finance.sqlite3`
- `~/jarvis_runtime/finance-system/imports/`
- `~/jarvis_runtime/finance-system/exports/`
- `~/jarvis_runtime/finance-system/reports/`
- `~/jarvis_runtime/finance-system/backups/`
- `~/jarvis_runtime/finance-system/secrets/`
- `~/jarvis_runtime/finance-system/logs/`

## Module responsibilities

- `config`: settings, runtime paths, logging, no business logic.
- `storage`: SQLite connection, schema, migrations, repositories, units of work.
- `models`: enums, DTOs, Decimal/date helpers.
- `ledger`: general transactions, cash, positions, Weighted Average Cost, performance.
- `crypto`: wallets, assets, crypto transactions, holdings, valuation; link fiat crypto buy/sell to general ledger.
- `imports`: CSV templates, dialect detection, row hashes, dry-run, import sessions.
- `market_data`: price providers, CoinGecko, cache, staleness.
- `fx`: rates, CHF conversion, missing/override logic.
- `dashboard`: Streamlit UI only; no business calculations embedded in page files.
- `reports`: Crypto PDF/HTML/Markdown report context and rendering.
- `audit`: audit log and audit requirement validators.
- `quality`: alerts, data-quality checks, git-safety scan.
- `cli`: setup/init-db/migrate/import-dry-run/git-safety commands.

## Migration strategy

Use lightweight custom migrations for MVP 1, not Alembic.

Add table:
- `schema_migrations(version, name, applied_at, checksum)`.

Rules:
- append-only migrations;
- tests build DB from empty to latest;
- no edits to already-applied migrations;
- destructive migrations require backup check;
- keep repository layer backend-neutral enough for later PostgreSQL.

PostgreSQL later can introduce Alembic if needed.

## Config/secrets

- `.env.example` committed.
- real `.env` never committed.
- `config.example/settings.example.toml` committed.
- API keys only local.
- runtime paths configurable.
- default runtime path outside repo and checked by tests.

## Test-first minimum

Must test before/alongside implementation:
- DB schema creatable.
- Schema version recorded.
- Runtime default outside repo.
- Synthetic fixtures load.
- Buy equity CHF.
- Buy equity USD with historical FX.
- Partial sell with Weighted Average Cost.
- Dividend cash/income effect.
- Initial position snapshot.
- Initial cash snapshot.
- Cash after start from transactions.
- Manual cash correction requires note/audit.
- Initial crypto holding.
- Crypto transfer between wallets.
- Crypto buy/sell with fiat links general ledger.
- Coin fee vs fiat fee handling.
- Missing FX creates critical alert.
- Manual FX override requires audit.
- Missing CoinGecko price creates warning.
- CSV dry run.
- Duplicate row hash blocked.
- Confirmed transaction requires audit.
- Git-safety blocks DB/env/credentials and allows synthetic examples.

## MVP task order

1. Project skeleton.
2. Config and runtime paths.
3. SQLite connection.
4. Schema and migration v001.
5. Models/enums/datatypes.
6. Audit log basis.
7. Quality alerts basis.
8. Synthetic fixtures.
9. Platforms/accounts importer.
10. Instruments importer.
11. Row hash / duplicate protection.
12. FX basic logic.
13. General transactions.
14. Cash calculation.
15. Weighted Average Cost.
16. Ledger position calculation.
17. Crypto wallets/assets.
18. Crypto holdings from snapshots.
19. Crypto transfers.
20. Crypto buy/sell with ledger coupling.
21. Crypto fees.
22. CoinGecko provider skeleton.
23. Complete CSV importers.
24. Git-safety scan.
25. Streamlit shell.
26. Command Center / Portfolio / Crypto pages.
27. Ledger / Wallets / Audit / Alerts pages.
28. Crypto report context.
29. Crypto PDF export.
30. End-to-end dummy portfolio.

## Implementation gate

Do not import real financial data until all of these work:
- schema creatable;
- synthetic fixtures load;
- audit basis;
- ledger buy CHF;
- ledger buy USD with FX;
- initial cash snapshot;
- crypto holding and transfer;
- CSV dry run;
- duplicate protection;
- git-safety scan.