# JARVIS Finance System – v0.5 Repo Blueprint / Implementation Plan

> **For Hermes:** Use `subagent-driven-development` skill to implement this plan task-by-task after explicit approval. Do not import real financial data until schema, dummy tests, git-safety and import dry-run are working.

**Goal:** Prepare the concrete MVP 1 repository, module boundaries, test-first sequence, migration strategy, configuration model and safety gates for implementing the JARVIS Finance System.

**Architecture:** MVP 1 uses a local-first Python application with SQLite as the authoritative local database, Streamlit as the dashboard, deterministic ledger services, CSV dry-run importers, audit/data-quality services and synthetic fixtures. Productive runtime data lives outside the Git repository.

**Tech Stack:** Python, SQLite, SQLAlchemy or a lightweight repository layer, Pandas, Plotly, Streamlit, pytest, Ruff/Black optional, WeasyPrint or Playwright for later PDF export.

**Version:** 0.5  
**Datum:** 2026-05-14  
**Status:** Repo Blueprint / Implementation Plan  
**Voraussetzung:** v0.4 Implementation Blueprint + v0.4.1 Korrekturrunde akzeptiert

---

## 1. Nicht-Ziele von v0.5

v0.5 sammelt keine neuen Fachfunktionen. v0.5 definiert, wie MVP 1 gebaut wird.

Nicht enthalten:

- echte Finanzdaten;
- Broker-spezifische Produktivimporte;
- automatischer Handel;
- vollständige Steuer-/Tax-Lot-Logik;
- Multi-User/Web-Deployment;
- FastAPI/React-Implementierung;
- Telegram-Produktivbuchung;
- On-chain Wallet-Scanning.

---

## 2. Repo- und Runtime-Struktur

## 2.1 Git-Repository

Empfohlener Repo-Name:

```text
jarvis-finance-system
```

Konkretes Ordnerlayout:

```text
jarvis-finance-system/
  pyproject.toml
  README.md
  .gitignore
  .env.example
  Makefile

  src/
    jarvis_finance/
      __init__.py
      app.py

      config/
        __init__.py
        settings.py
        paths.py
        logging.py

      storage/
        __init__.py
        database.py
        schema.py
        migrations.py
        repositories.py
        units_of_work.py

      models/
        __init__.py
        enums.py
        datatypes.py
        dto.py

      ledger/
        __init__.py
        transactions.py
        cash.py
        positions.py
        cost_basis.py
        performance.py
        validators.py

      crypto/
        __init__.py
        wallets.py
        assets.py
        transactions.py
        holdings.py
        valuation.py
        validators.py

      imports/
        __init__.py
        csv_dialect.py
        row_hash.py
        dry_run.py
        validators.py
        accounts_importer.py
        instruments_importer.py
        transactions_importer.py
        crypto_wallets_importer.py
        crypto_holdings_importer.py
        crypto_transactions_importer.py
        watchlist_importer.py
        cash_balances_importer.py

      market_data/
        __init__.py
        providers.py
        coingecko.py
        cache.py
        staleness.py

      fx/
        __init__.py
        rates.py
        providers.py
        conversion.py
        overrides.py

      dashboard/
        __init__.py
        main.py
        pages/
          00_command_center.py
          01_portfolio.py
          02_platforms.py
          03_equities_etfs.py
          04_crypto.py
          05_wallets.py
          06_ledger.py
          07_watchlist.py
          08_reports.py
          09_alerts.py
          10_audit.py
          11_settings_data_quality.py
        components/
          __init__.py
          tables.py
          forms.py
          charts.py
          warnings.py

      reports/
        __init__.py
        crypto_pdf.py
        templates/
          crypto_report.md.j2
          crypto_report.html.j2
        render.py
        metadata.py

      audit/
        __init__.py
        log.py
        decorators.py
        validators.py

      quality/
        __init__.py
        alerts.py
        rules.py
        checks.py
        git_safety.py

      cli/
        __init__.py
        main.py

  tests/
    conftest.py
    fixtures/
      accounts.csv
      instruments.csv
      transactions.csv
      crypto_wallets.csv
      crypto_holdings_initial.csv
      crypto_transactions.csv
      watchlist.csv
      cash_balances_initial.csv
    unit/
      test_schema.py
      test_settings.py
      test_audit.py
      test_ledger_equities.py
      test_ledger_cash.py
      test_fx.py
      test_crypto.py
      test_imports.py
      test_quality.py
      test_git_safety.py
    integration/
      test_dummy_data_load.py
      test_end_to_end_dummy_portfolio.py

  examples/
    README.md
    synthetic/
      accounts.csv
      instruments.csv
      transactions.csv
      crypto_wallets.csv
      crypto_holdings_initial.csv
      crypto_transactions.csv
      watchlist.csv
      cash_balances_initial.csv

  docs/
    architecture/
      v0.4-implementation-blueprint.md
      v0.4.1-corrections.md
      v0.5-repo-blueprint.md
    decisions/
      ADR-0001-mvp-stack-streamlit-sqlite-python.md
      ADR-0002-runtime-data-outside-repo.md
      ADR-0003-weighted-average-cost-mvp.md
    plans/
      2026-05-14-mvp1-implementation-plan.md

  config.example/
    settings.example.toml
    providers.example.toml
```

## 2.2 Produktive Runtime ausserhalb Repo

Standard:

```text
~/jarvis_runtime/finance-system/
  data/
    finance.sqlite3
  imports/
  exports/
  reports/
  backups/
  secrets/
  logs/
```

Diese Pfade sind konfigurierbar, aber der Default bleibt ausserhalb des Repos.

## 2.3 Git-Inhalt

Git enthält nur:

- Code;
- technische Dokumentation;
- synthetische Fixtures;
- Beispielkonfigurationen;
- Tests.

Git enthält niemals:

- echte SQLite-Datenbanken;
- echte CSV-/JSON-Exports;
- echte Reports;
- echte Portfolioauszüge;
- API Keys;
- Secrets;
- OAuth-Dateien;
- produktive Logs mit Finanzwerten.

---

## 3. Modulverantwortung

## 3.1 `config/`

**Zweck:** Einstellungen, Pfade, Umgebungsvariablen, Logging-Konfiguration.

**Wichtigste Dateien:**

- `settings.py` – lädt `.env`, TOML/Defaults, validiert Settings.
- `paths.py` – trennt Repo-Pfade und Runtime-Pfade.
- `logging.py` – Logging ohne Secrets/Finanzwerte.

**Zentrale Funktionen/Klassen:**

- `Settings`
- `RuntimePaths`
- `load_settings()`
- `ensure_runtime_dirs()`

**Abhängigkeiten:** Python stdlib, optional pydantic-settings oder dataclasses.

**Nicht hier:** Business-Logik, DB-Zugriff, Importvalidierung.

---

## 3.2 `storage/`

**Zweck:** SQLite-Verbindung, Schema, Migrationen, Repositories, Transaktionsgrenzen.

**Wichtigste Dateien:**

- `database.py` – Connection/Engine.
- `schema.py` – aktuelle Tabellen-Definition.
- `migrations.py` – Schema-Versionen und Migration Runner.
- `repositories.py` – CRUD-Repositories.
- `units_of_work.py` – kontrollierte Schreibtransaktionen.

**Zentrale Funktionen/Klassen:**

- `create_engine_or_connection()`
- `init_database()`
- `get_schema_version()`
- `apply_migrations()`
- `Repository`
- `UnitOfWork`

**Abhängigkeiten:** SQLite, SQLAlchemy oder sqlite3, config.

**Nicht hier:** Performance-Berechnung, FX-Logik, CSV-Parsing, Dashboard.

---

## 3.3 `models/`

**Zweck:** Enums, DTOs, Decimal-/Date-Hilfen und fachliche Typen ohne DB-Seiteneffekte.

**Wichtigste Dateien:**

- `enums.py`
- `datatypes.py`
- `dto.py`

**Zentrale Funktionen/Klassen:**

- `TransactionType`
- `CryptoTransactionType`
- `QualityStatus`
- `MoneyAmount`
- `Quantity`

**Abhängigkeiten:** Python stdlib, Decimal.

**Nicht hier:** Speicherung oder Berechnung mit DB-Zugriff.

---

## 3.4 `ledger/`

**Zweck:** Allgemeines Ledger: Wertpapiertransaktionen, Cash, Positionen, Weighted Average Cost, Performance.

**Wichtigste Dateien:**

- `transactions.py` – Erfassung/Validierung allgemeiner Transaktionen.
- `cash.py` – Cash-Berechnung aus Initial Cash + Transaktionen.
- `positions.py` – Positionen aus Initial Snapshots + Transaktionen.
- `cost_basis.py` – Weighted Average Cost.
- `performance.py` – Realisierte/unrealisierte Performance.
- `validators.py` – Fachvalidierungen.

**Zentrale Funktionen/Klassen:**

- `record_transaction()`
- `calculate_cash_balance()`
- `calculate_positions_snapshot()`
- `apply_buy()`
- `apply_sell()`
- `calculate_weighted_average_cost()`

**Abhängigkeiten:** storage, models, fx, audit, quality.

**Nicht hier:** Crypto-spezifische Wallet-Transfers, CoinGecko, Streamlit.

---

## 3.5 `crypto/`

**Zweck:** Crypto-Wallets, Assets, Crypto-Transaktionen, Holdings, Valuation.

**Wichtigste Dateien:**

- `wallets.py`
- `assets.py`
- `transactions.py`
- `holdings.py`
- `valuation.py`
- `validators.py`

**Zentrale Funktionen/Klassen:**

- `record_crypto_buy()`
- `record_crypto_sell()`
- `record_crypto_transfer()`
- `calculate_crypto_holdings()`
- `link_crypto_transaction_to_ledger_transaction()`

**Abhängigkeiten:** storage, models, ledger, market_data, fx, audit, quality.

**Nicht hier:** Aktien/ETF-Positionen, allgemeiner CSV-Dialekt, Dashboard-Layout.

**Wichtige Kopplungsregel:** Crypto mit Fiat-/CHF-Auswirkung erzeugt bzw. referenziert allgemeine Ledger-Transaktionen. Reine Wallet-Transfers ohne Fiat-Bewegung bleiben nur in `crypto_transactions`.

---

## 3.6 `imports/`

**Zweck:** CSV Templates, Dialekterkennung, Dry Run, Row Hashes, Validierungsfehler, Import Sessions.

**Wichtigste Dateien:**

- `csv_dialect.py`
- `row_hash.py`
- `dry_run.py`
- `validators.py`
- je Template ein Importer.

**Zentrale Funktionen/Klassen:**

- `detect_dialect()`
- `normalize_row()`
- `compute_row_hash()`
- `dry_run_import()`
- `commit_import_session()`

**Abhängigkeiten:** storage, ledger, crypto, audit, quality.

**Nicht hier:** Anbieter-spezifisches Scraping, produktive Broker-APIs, direkte UI.

---

## 3.7 `market_data/`

**Zweck:** Preisprovider, CoinGecko, Cache, Staleness-Status.

**Wichtigste Dateien:**

- `providers.py`
- `coingecko.py`
- `cache.py`
- `staleness.py`

**Zentrale Funktionen/Klassen:**

- `PriceProvider`
- `CoinGeckoClient`
- `fetch_crypto_prices()`
- `mark_stale_prices()`

**Abhängigkeiten:** storage, config, quality.

**Nicht hier:** Ledger-Buchungen, Steuerlogik, Dashboard-Komponenten.

---

## 3.8 `fx/`

**Zweck:** Historische und aktuelle FX-Kurse, CHF-Konvertierung, Missing/Override-Logik.

**Wichtigste Dateien:**

- `rates.py`
- `providers.py`
- `conversion.py`
- `overrides.py`

**Zentrale Funktionen/Klassen:**

- `get_fx_rate()`
- `convert_to_chf()`
- `record_manual_fx_override()`
- `validate_fx_for_transaction()`

**Abhängigkeiten:** storage, audit, quality.

**Nicht hier:** Wertpapier- oder Crypto-Mengenberechnung.

---

## 3.9 `dashboard/`

**Zweck:** Streamlit UI.

**Wichtigste Dateien:**

- `main.py`
- `pages/*.py`
- `components/*.py`

**Zentrale Funktionen/Klassen:**

- `render_command_center()`
- `render_portfolio_page()`
- `render_crypto_page()`
- `render_ledger_page()`

**Abhängigkeiten:** config, storage, ledger, crypto, reports, quality, audit.

**Nicht hier:** Fachberechnung direkt implementieren. Dashboard ruft Services auf, es ist nicht die Buchhaltung selbst.

---

## 3.10 `reports/`

**Zweck:** Report-Erzeugung, zuerst Crypto-PDF/HTML/Markdown.

**Wichtigste Dateien:**

- `crypto_pdf.py`
- `render.py`
- `metadata.py`
- Templates unter `reports/templates/`.

**Zentrale Funktionen/Klassen:**

- `build_crypto_report_context()`
- `render_crypto_report_html()`
- `export_crypto_report_pdf()`
- `record_report_metadata()`

**Abhängigkeiten:** storage, crypto, market_data, quality, audit.

**Nicht hier:** Importlogik, Ledger-Änderungen.

---

## 3.11 `audit/`

**Zweck:** Audit Log für jede bestätigte Änderung.

**Wichtigste Dateien:**

- `log.py`
- `decorators.py`
- `validators.py`

**Zentrale Funktionen/Klassen:**

- `record_audit_event()`
- `require_audit_for_confirmed_transaction()`
- `audit_context()`

**Abhängigkeiten:** storage, models.

**Nicht hier:** Entscheidung, was fachlich erlaubt ist; das bleibt in ledger/crypto/imports.

---

## 3.12 `quality/`

**Zweck:** Alerts, Datenqualität, Git-Safety, Validierungsberichte.

**Wichtigste Dateien:**

- `alerts.py`
- `rules.py`
- `checks.py`
- `git_safety.py`

**Zentrale Funktionen/Klassen:**

- `create_alert()`
- `run_data_quality_checks()`
- `check_missing_fx()`
- `check_missing_coingecko_price()`
- `run_git_safety_scan()`

**Abhängigkeiten:** storage, config.

**Nicht hier:** Berechnung von Positionen oder UI.

---

## 3.13 `cli/`

**Zweck:** Kommandos für Setup, DB Init, Import Dry Run, Testsupport.

**Wichtigste Dateien:**

- `main.py`

**Zentrale Kommandos:**

```bash
finance init-db
finance migrate
finance load-fixtures
finance import-dry-run examples/synthetic/transactions.csv
finance git-safety-scan
```

**Abhängigkeiten:** alle Service-Module.

**Nicht hier:** langlebige Business-Logik.

---

## 4. Migration-Strategie

## 4.1 MVP-Entscheidung

Für MVP 1 wird eine eigene leichte Migration verwendet, nicht Alembic.

Begründung:

- SQLite-first;
- überschaubares Schema;
- weniger Setup-Komplexität;
- leichter testbar;
- kontrollierte Migrationen reichen für MVP.

## 4.2 Schema-Versionierung

Eine Tabelle `schema_migrations` wird angelegt:

```text
version INTEGER PRIMARY KEY
name TEXT NOT NULL
applied_at TEXT NOT NULL
checksum TEXT NOT NULL
```

Jede Migration ist eine nummerierte Python-Funktion oder SQL-Datei:

```text
001_initial_schema
002_indexes_and_constraints
003_seed_reference_values_optional
```

## 4.3 Migrationsregeln

- Migrationen sind append-only.
- Einmal angewendete Migrationen werden nicht verändert.
- Tests erstellen DB von leerem Zustand bis aktuelle Version.
- Jede Migration hat Smoke-Test.
- Destruktive Migrationen erst nach Backup-Check.

## 4.4 PostgreSQL-Vorbereitung

PostgreSQL wird vorbereitet durch:

- SQLAlchemy-kompatible Typen oder minimale SQL-Abstraktion;
- keine SQLite-spezifische Business-Logik;
- IDs als TEXT/UUID-kompatibel;
- ISO-Zeitstrings oder später Timestamp-Typen sauber kapseln;
- Repository-Schicht statt überall roher SQL-Zugriff;
- Migrationen fachlich getrennt von Storage-Backend.

Alembic kann später eingeführt werden, wenn PostgreSQL oder komplexere Schemaentwicklung nötig wird.

---

## 5. Konfiguration und Secrets

## 5.1 `.env.example`

Beispiel:

```text
JARVIS_FINANCE_ENV=local
JARVIS_FINANCE_RUNTIME_DIR=/home/USER/jarvis_runtime/finance-system
JARVIS_FINANCE_DB_PATH=/home/USER/jarvis_runtime/finance-system/data/finance.sqlite3
JARVIS_FINANCE_LOG_LEVEL=INFO
COINGECKO_API_KEY=
FX_PROVIDER_API_KEY=
```

Die echte `.env` wird nie committed.

## 5.2 `config.example/settings.example.toml`

```toml
[app]
base_currency = "CHF"
timezone = "Europe/Zurich"

[runtime]
base_dir = "~/jarvis_runtime/finance-system"
data_dir = "~/jarvis_runtime/finance-system/data"
reports_dir = "~/jarvis_runtime/finance-system/reports"
imports_dir = "~/jarvis_runtime/finance-system/imports"
exports_dir = "~/jarvis_runtime/finance-system/exports"
backups_dir = "~/jarvis_runtime/finance-system/backups"

[database]
path = "~/jarvis_runtime/finance-system/data/finance.sqlite3"

[market_data]
crypto_provider = "coingecko"
price_stale_after_hours = 24

[security]
require_git_safety_scan = true
block_runtime_inside_repo = true
```

## 5.3 Secret-Regeln

- API Keys nur lokal in `.env` oder lokalem Secret Store.
- Keine Keys in TOML-Beispielen.
- Keine Keys in DB.
- Keine Keys in Logs.
- Keine Keys in Reports.
- Keine Keys in GitHub Actions, ausser bewusst als GitHub Secret und ohne echte Finanzdatenzugriffe im CI.

---

## 6. Dummy-Daten und echte Daten strikt trennen

## 6.1 Synthetische Daten erlaubt

Synthetische Daten dürfen liegen in:

```text
examples/synthetic/
tests/fixtures/
```

Bedingungen:

- klar als Demo erkennbar;
- keine echten Institutionsexporte;
- keine echten Wallet-Adressen;
- keine echten Depotwerte;
- keine echten Transaktionshistorien;
- keine echten Kundennummern;
- keine realen Portfolioauszüge.

## 6.2 Echte Daten

Echte Daten müssen liegen in:

```text
~/jarvis_runtime/finance-system/
```

oder einem bewusst gewählten externen, gitignorierten Runtime-Pfad.

## 6.3 Schutzmechanismen

- `.gitignore` blockiert sensible Muster.
- `quality/git_safety.py` scannt vor Commit.
- Tests prüfen, dass Runtime-Default ausserhalb Repo liegt.
- Importer schreiben echte Uploads nicht nach `examples/`.
- Reports werden standardmässig in Runtime-Reports geschrieben.

## 6.4 Minimal `.gitignore`

```text
.env
*.env
*token*
*credential*
*client_secret*
*.key
*.pem

# Runtime and real data
local_runtime/
runtime/
data/
imports/
exports/
reports/
backups/
secrets/
logs/

# Databases and dumps
*.db
*.sqlite
*.sqlite3
*.dump
*.parquet

# Real documents and exports
*.xlsx
*.xls
*.pdf
*.docx
*.csv
*.json

# Allow synthetic fixtures/examples only
!examples/**/*.csv
!examples/**/*.json
!tests/fixtures/**/*.csv
!tests/fixtures/**/*.json
!config.example/**/*.json
```

Hinweis: Die Ausnahmen dürfen nur synthetische Daten enthalten. Eine private GitHub-Repo ist kein Tresor. Überraschend, aber wahr.

---

## 7. Test-first Plan

## 7.1 Testgrundsatz

Jede Kernfunktion wird zuerst oder parallel mit Tests gebaut. MVP-Code startet nicht mit echten Daten.

## 7.2 Mindesttests

### DB und Setup

- `test_schema.py::test_db_schema_can_be_created`
- `test_schema.py::test_schema_version_recorded`
- `test_settings.py::test_runtime_default_outside_repo`

### Dummy-Daten

- `test_dummy_data_load.py::test_synthetic_fixtures_load`
- `test_dummy_data_load.py::test_no_fixture_contains_forbidden_real_markers`

### Allgemeines Ledger

- `test_ledger_equities.py::test_buy_equity_chf_updates_position_and_cash`
- `test_ledger_equities.py::test_buy_equity_usd_uses_historical_fx`
- `test_ledger_equities.py::test_partial_sell_uses_weighted_average_cost`
- `test_ledger_equities.py::test_dividend_increases_cash_and_income`
- `test_ledger_equities.py::test_initial_position_snapshot_creates_start_position`

### Cash

- `test_ledger_cash.py::test_initial_cash_snapshot_is_start_truth`
- `test_ledger_cash.py::test_cash_after_start_is_calculated_from_transactions`
- `test_ledger_cash.py::test_manual_cash_correction_requires_note_and_audit`

### Crypto

- `test_crypto.py::test_initial_crypto_holding_from_confirmed_snapshot`
- `test_crypto.py::test_crypto_transfer_moves_quantity_between_wallets`
- `test_crypto.py::test_crypto_buy_with_fiat_links_general_ledger_transaction`
- `test_crypto.py::test_crypto_sell_with_fiat_links_general_ledger_transaction`
- `test_crypto.py::test_coin_fee_reduces_coin_quantity`
- `test_crypto.py::test_fiat_fee_creates_general_ledger_fee`

### FX und Market Data

- `test_fx.py::test_missing_fx_creates_critical_alert`
- `test_fx.py::test_manual_fx_override_requires_audit`
- `test_quality.py::test_missing_coingecko_price_creates_warning`

### CSV Import

- `test_imports.py::test_csv_dry_run_valid_file`
- `test_imports.py::test_csv_duplicate_row_hash_blocked`
- `test_imports.py::test_import_does_not_commit_on_dry_run`

### Audit und Safety

- `test_audit.py::test_confirmed_transaction_requires_audit_entry`
- `test_git_safety.py::test_git_safety_blocks_sqlite_database`
- `test_git_safety.py::test_git_safety_blocks_env_and_credentials`
- `test_git_safety.py::test_git_safety_allows_synthetic_examples`

---

## 8. Datei-/Task-Reihenfolge für MVP 1

Jeder Task ist klein, überprüfbar und sollte separat commitbar sein.

### Task 1: Projektgerüst erstellen

**Objective:** Repo-Layout, Python-Package und leere Module anlegen.

**Files:**
- Create: alle `__init__.py`
- Create: `pyproject.toml`
- Create: `README.md`
- Create: `.gitignore`
- Create: `.env.example`

**Verification:**

```bash
python -m compileall src tests
```

Expected: keine Syntaxfehler.

---

### Task 2: Config und Runtime-Pfade

**Objective:** Settings laden und Runtime standardmässig ausserhalb Repo erzwingen.

**Files:**
- Create: `src/jarvis_finance/config/settings.py`
- Create: `src/jarvis_finance/config/paths.py`
- Test: `tests/unit/test_settings.py`

**Test first:**

- Runtime-Default beginnt mit `~/jarvis_runtime/finance-system`.
- Runtime innerhalb Repo wird blockiert, falls `block_runtime_inside_repo=true`.

**Verification:**

```bash
pytest tests/unit/test_settings.py -v
```

---

### Task 3: SQLite-Verbindung

**Objective:** DB-Verbindung anhand Settings erzeugen.

**Files:**
- Create: `src/jarvis_finance/storage/database.py`
- Test: `tests/unit/test_schema.py`

**Verification:**

```bash
pytest tests/unit/test_schema.py::test_db_schema_can_be_created -v
```

Expected zuerst FAIL, nach Implementierung PASS.

---

### Task 4: Schema und Migration v001

**Objective:** Tabellen aus v0.4/v0.4.1 als initiales SQLite-Schema anlegen.

**Files:**
- Create: `src/jarvis_finance/storage/schema.py`
- Create: `src/jarvis_finance/storage/migrations.py`
- Test: `tests/unit/test_schema.py`

**Verification:**

```bash
pytest tests/unit/test_schema.py -v
```

---

### Task 5: Models/Enums/Datatypes

**Objective:** Gemeinsame Typen für TransactionType, QualityStatus, Decimal-Hilfen.

**Files:**
- Create: `src/jarvis_finance/models/enums.py`
- Create: `src/jarvis_finance/models/datatypes.py`
- Create: `src/jarvis_finance/models/dto.py`

**Verification:**

```bash
pytest tests/unit -k "settings or schema" -v
python -m compileall src
```

---

### Task 6: Audit Log Basis

**Objective:** Audit-Einträge schreiben und Pflichtprüfung vorbereiten.

**Files:**
- Create: `src/jarvis_finance/audit/log.py`
- Create: `src/jarvis_finance/audit/validators.py`
- Test: `tests/unit/test_audit.py`

**Verification:**

```bash
pytest tests/unit/test_audit.py -v
```

---

### Task 7: Quality Alerts Basis

**Objective:** Alerts erzeugen und abfragen.

**Files:**
- Create: `src/jarvis_finance/quality/alerts.py`
- Create: `src/jarvis_finance/quality/rules.py`
- Test: `tests/unit/test_quality.py`

**Verification:**

```bash
pytest tests/unit/test_quality.py -v
```

---

### Task 8: Dummy Fixtures anlegen

**Objective:** synthetische CSVs gemäss v0.4 Templates erstellen.

**Files:**
- Create: `tests/fixtures/*.csv`
- Create: `examples/synthetic/*.csv`
- Test: `tests/integration/test_dummy_data_load.py`

**Verification:**

```bash
pytest tests/integration/test_dummy_data_load.py -v
```

---

### Task 9: Plattformen und Accounts importieren

**Objective:** Plattformen/Accounts aus synthetischem CSV im Dry Run und Commit laden.

**Files:**
- Create: `src/jarvis_finance/imports/accounts_importer.py`
- Modify: `src/jarvis_finance/imports/dry_run.py`
- Test: `tests/unit/test_imports.py`

**Verification:**

```bash
pytest tests/unit/test_imports.py::test_csv_dry_run_valid_file -v
```

---

### Task 10: Instruments importieren

**Objective:** Instrumente validieren und laden.

**Files:**
- Create: `src/jarvis_finance/imports/instruments_importer.py`
- Test: `tests/unit/test_imports.py`

**Verification:**

```bash
pytest tests/unit/test_imports.py -k instruments -v
```

---

### Task 11: Row Hash und Duplikatschutz

**Objective:** CSV-Zeilen idempotent importieren.

**Files:**
- Create: `src/jarvis_finance/imports/row_hash.py`
- Test: `tests/unit/test_imports.py`

**Verification:**

```bash
pytest tests/unit/test_imports.py::test_csv_duplicate_row_hash_blocked -v
```

---

### Task 12: FX-Grundlogik

**Objective:** CHF-Konvertierung, fehlender FX-Alert, manueller Override.

**Files:**
- Create: `src/jarvis_finance/fx/rates.py`
- Create: `src/jarvis_finance/fx/conversion.py`
- Create: `src/jarvis_finance/fx/overrides.py`
- Test: `tests/unit/test_fx.py`

**Verification:**

```bash
pytest tests/unit/test_fx.py -v
```

---

### Task 13: Allgemeine Transactions

**Objective:** Transaktionen speichern, validieren, Audit erzwingen.

**Files:**
- Create: `src/jarvis_finance/ledger/transactions.py`
- Create: `src/jarvis_finance/ledger/validators.py`
- Test: `tests/unit/test_ledger_equities.py`

**Verification:**

```bash
pytest tests/unit/test_ledger_equities.py::test_buy_equity_chf_updates_position_and_cash -v
```

---

### Task 14: Cash-Berechnung

**Objective:** Cash aus Initial Cash + Transaktionen berechnen.

**Files:**
- Create: `src/jarvis_finance/ledger/cash.py`
- Test: `tests/unit/test_ledger_cash.py`

**Verification:**

```bash
pytest tests/unit/test_ledger_cash.py -v
```

---

### Task 15: Weighted Average Cost

**Objective:** MVP-Cost-Basis-Methode implementieren.

**Files:**
- Create: `src/jarvis_finance/ledger/cost_basis.py`
- Modify: `src/jarvis_finance/ledger/positions.py`
- Test: `tests/unit/test_ledger_equities.py`

**Verification:**

```bash
pytest tests/unit/test_ledger_equities.py::test_partial_sell_uses_weighted_average_cost -v
```

---

### Task 16: Ledger-Positionsberechnung

**Objective:** Buy, Sell, Dividend, Initial Snapshot zu Positionen verarbeiten.

**Files:**
- Create: `src/jarvis_finance/ledger/positions.py`
- Create: `src/jarvis_finance/ledger/performance.py`
- Test: `tests/unit/test_ledger_equities.py`

**Verification:**

```bash
pytest tests/unit/test_ledger_equities.py -v
```

---

### Task 17: Crypto Wallets und Assets

**Objective:** Wallets und Crypto Assets validieren/speichern.

**Files:**
- Create: `src/jarvis_finance/crypto/wallets.py`
- Create: `src/jarvis_finance/crypto/assets.py`
- Test: `tests/unit/test_crypto.py`

**Verification:**

```bash
pytest tests/unit/test_crypto.py -k "wallet or asset" -v
```

---

### Task 18: Crypto Holdings aus Initial Snapshot

**Objective:** Crypto-Holdings aus bestätigten Initial-Snapshots berechnen.

**Files:**
- Create: `src/jarvis_finance/crypto/holdings.py`
- Test: `tests/unit/test_crypto.py`

**Verification:**

```bash
pytest tests/unit/test_crypto.py::test_initial_crypto_holding_from_confirmed_snapshot -v
```

---

### Task 19: Crypto Transfers

**Objective:** Wallet-Transfer ohne Fiat-Bewegung korrekt buchen.

**Files:**
- Create: `src/jarvis_finance/crypto/transactions.py`
- Test: `tests/unit/test_crypto.py`

**Verification:**

```bash
pytest tests/unit/test_crypto.py::test_crypto_transfer_moves_quantity_between_wallets -v
```

---

### Task 20: Crypto Buy/Sell mit Ledger-Kopplung

**Objective:** Crypto-Kauf/-Verkauf mit Fiat-Betrag an allgemeines Ledger koppeln.

**Files:**
- Modify: `src/jarvis_finance/crypto/transactions.py`
- Modify: `src/jarvis_finance/ledger/transactions.py`
- Test: `tests/unit/test_crypto.py`

**Verification:**

```bash
pytest tests/unit/test_crypto.py -k "fiat_links_general_ledger" -v
```

---

### Task 21: Crypto Fees

**Objective:** Coin-Fee und Fiat-Fee getrennt korrekt behandeln.

**Files:**
- Modify: `src/jarvis_finance/crypto/transactions.py`
- Modify: `src/jarvis_finance/ledger/transactions.py`
- Test: `tests/unit/test_crypto.py`

**Verification:**

```bash
pytest tests/unit/test_crypto.py -k "fee" -v
```

---

### Task 22: CoinGecko Provider Skeleton

**Objective:** Preisabruf abstrahieren und fehlende Preise warnen.

**Files:**
- Create: `src/jarvis_finance/market_data/providers.py`
- Create: `src/jarvis_finance/market_data/coingecko.py`
- Create: `src/jarvis_finance/market_data/cache.py`
- Test: `tests/unit/test_quality.py`

**Verification:**

```bash
pytest tests/unit/test_quality.py::test_missing_coingecko_price_creates_warning -v
```

---

### Task 23: CSV Importer komplettieren

**Objective:** Alle MVP CSV Templates als Dry Run und Commit unterstützen.

**Files:**
- Create/Modify: `src/jarvis_finance/imports/*_importer.py`
- Test: `tests/unit/test_imports.py`

**Verification:**

```bash
pytest tests/unit/test_imports.py -v
```

---

### Task 24: Git-Safety Scan

**Objective:** Verbotene Dateien/Secrets vor Commit erkennen.

**Files:**
- Create: `src/jarvis_finance/quality/git_safety.py`
- Test: `tests/unit/test_git_safety.py`

**Verification:**

```bash
pytest tests/unit/test_git_safety.py -v
```

---

### Task 25: Streamlit Grundshell

**Objective:** Dashboard startet mit Navigation und liest Dummy-DB.

**Files:**
- Create: `src/jarvis_finance/dashboard/main.py`
- Create: `src/jarvis_finance/dashboard/pages/*.py`

**Verification:**

```bash
streamlit run src/jarvis_finance/dashboard/main.py
```

Expected: App startet lokal mit Dummy-Daten, keine echten Daten nötig.

---

### Task 26: Dashboard Command Center / Portfolio / Crypto

**Objective:** Erste lesende Seiten für Kernübersichten.

**Files:**
- Modify: `dashboard/pages/00_command_center.py`
- Modify: `dashboard/pages/01_portfolio.py`
- Modify: `dashboard/pages/04_crypto.py`

**Verification:** Dummy-Portfolio sichtbar, Alerts sichtbar, keine Schreibaktion nötig.

---

### Task 27: Ledger / Wallets / Audit / Alerts Seiten

**Objective:** Kontroll- und Detailseiten ergänzen.

**Files:**
- Modify: `dashboard/pages/05_wallets.py`
- Modify: `dashboard/pages/06_ledger.py`
- Modify: `dashboard/pages/09_alerts.py`
- Modify: `dashboard/pages/10_audit.py`

**Verification:** Dummy-Daten filterbar, Audit-Timeline sichtbar.

---

### Task 28: Crypto Report Context

**Objective:** Crypto-PDF-Datenkontext aus DB bauen.

**Files:**
- Create: `src/jarvis_finance/reports/crypto_pdf.py`
- Create: `src/jarvis_finance/reports/templates/crypto_report.md.j2`
- Test: später `tests/unit/test_reports.py`

**Verification:** Markdown/HTML aus Dummy-Daten erzeugbar.

---

### Task 29: Crypto PDF Export

**Objective:** PDF mit Dummy-Daten erzeugen, in Runtime-Reports speichern.

**Files:**
- Create: `src/jarvis_finance/reports/render.py`
- Modify: `src/jarvis_finance/reports/crypto_pdf.py`

**Verification:** PDF liegt unter Runtime-Reports, nicht im Repo.

---

### Task 30: End-to-End Dummy Portfolio

**Objective:** Vollständiger MVP-Smoke-Test mit synthetischen Daten.

**Files:**
- Create: `tests/integration/test_end_to_end_dummy_portfolio.py`

**Verification:**

```bash
pytest tests/unit tests/integration -v
```

Expected: alle Tests grün, keine echten Daten, Git-Safety OK.

---

## 9. Akzeptanzkriterien für Start der Implementierung

Mit MVP-Code darf begonnen werden, wenn v0.5 akzeptiert ist und folgende Bedingungen gelten:

1. v0.4 und v0.4.1 gelten als fachlich/technische Grundlage.
2. Repo-Struktur ist akzeptiert.
3. Runtime-Pfad ausserhalb Repo ist verbindlich.
4. `.gitignore`, `.env.example` und Config-Beispiele sind vor Datenarbeit vorhanden.
5. SQLite-Migrationstrategie ist akzeptiert.
6. Test-first Mindestliste ist akzeptiert.
7. Dummy-Datenstrategie ist akzeptiert.
8. Git-Safety-Test ist Pflicht vor echten Daten.
9. CSV Import startet mit Dry Run, nicht direktem Commit.
10. Keine echten Finanzdaten werden importiert, bevor mindestens folgende Punkte funktionieren:
    - Schema erzeugbar;
    - synthetische Fixtures ladbar;
    - Audit Log Basis;
    - Ledger-Kauf CHF;
    - Ledger-Kauf USD mit FX;
    - Initial Cash Snapshot;
    - Crypto Holding und Transfer;
    - CSV Dry Run;
    - Duplikatschutz;
    - Git-Safety Scan.

---

## 10. Handoff zur Umsetzung

Nach Freigabe von v0.5 soll die eigentliche Implementierung in kleinen, überprüfbaren Schritten erfolgen.

Empfohlenes Vorgehen:

- je Task ein kleiner Commit;
- TDD für Ledger/Crypto/FX/Import/Safety;
- keine echten Daten vor Safety Gate;
- nach jedem Task Tests ausführen;
- bei grösseren Modulen Subagent-Implementierung mit Review:
  - Spec Compliance Review;
  - Code Quality Review;
  - erst danach nächster Task.

Das Ziel ist nicht, schnell eine hübsche Oberfläche zu haben. Das Ziel ist, dass die Buchhaltung stimmt, bevor sie Make-up trägt.