# MVP Streamlit Dashboard Pattern

Use this reference for the first local dashboard block of the JARVIS Finance System.

## Scope

Build a safe, local, read-first Streamlit MVP over a local SQLite database with synthetic data only.

Required pages for the v0.5 shell:

- Command Center
- Portfolio
- Platforms
- Equities/ETFs
- Crypto
- Wallets
- Ledger
- Watchlist
- Reports
- Alerts
- Audit
- Settings/Data Quality

## Safety rules

- Never import real finance files, portfolio exports, wallet files, wallet addresses, secrets, runtime data, DBs, reports, or cache files into the repo.
- Do not call market-data providers from dashboard page render functions.
- CoinGecko/current crypto prices shown in the dashboard must come only from local DB/cache tables.
- If no DB exists, show a clear error and an explicit action/hint for creating a synthetic demo DB; do not automatically create or mutate real data.
- Runtime paths must remain outside the repo; keep a test that blocks in-repo runtime configuration.
- Alert lifecycle mutations (`acknowledge`, `resolve`, `mute`) should remain read-only in the first MVP unless explicit mutation code and tests exist.

## Implementation pattern

- Keep `dashboard/main.py` thin: load settings, validate runtime, connect to an existing SQLite DB, show navigation, dispatch to page modules.
- Put all SQL/derived read models in a separate dashboard data module so they can be unit-tested without Streamlit.
- Use simple page modules with a `PAGE_TITLE` and `render(st, conn)` signature.
- Use a tiny fake Streamlit object in tests for page smoke rendering; avoid requiring Streamlit to be installed for unit tests.
- Use Python `Decimal` for crypto quantities/prices and format via `format(value, "f")`; never format crypto amounts through float.
- Tables are enough for MVP. Prefer correctness, clear status/warnings, and data truth over polished UI.

## Demo data pattern

- Seed demo DB only by explicit user action or test helper.
- Use `tests/fixtures/` and domain APIs for synthetic records if importers are stricter than legacy fixtures.
- Store synthetic crypto prices in local DB/cache with provider metadata such as `synthetic-cache`.
- Add synthetic audit and alert records so Audit/Alerts pages can be exercised.

## Minimum tests

- Dashboard modules import and selected page modules smoke-render.
- Dashboard reader functions return expected synthetic data.
- Crypto page render does not call CoinGecko/API provider methods.
- Decimal crypto quantities preserve exact text formatting and avoid scientific notation.
- Alert lifecycle fields load readably (`status`, `priority`, `occurrence_count`, `last_seen_at`, `fingerprint`, `dedup_key`).
- Runtime path inside repo remains blocked.

## Verification sequence

Run from repo root before committing/pushing:

```bash
find . -type d \( -name __pycache__ -o -name .pytest_cache \) -exec rm -rf {} +
PYTHONPATH=src python -m compileall src tests
PYTHONPATH=src pytest tests -q
find . -type d \( -name __pycache__ -o -name .pytest_cache \) -exec rm -rf {} +
PYTHONPATH=src python -m jarvis_finance.cli.main git-safety-scan .
git status --short
```

Important: `pytest` may recreate `.pytest_cache`; remove it before Git-safety because the finance Git-safety scanner intentionally blocks runtime/cache files.