ETL Pipeline

De ETL (Extract-Transform-Load) pipeline synchroniseert data van de lokale Helios trading engine naar het cloudplatform. Het principe is eenvoudig: lokaal pusht naar cloud, nooit andersom.

Zie Architectuur voor het ecosysteem-overzicht.

3-stream dataflowarchitectuur

Stream 1: Equity Data

Wekelijkse equity-snapshots van de engine naar de cloud.

Veld	Type	Beschrijving
date	DATE	Week-einddatum
equity	NUMERIC	Totale portefeuillewaarde
cash	NUMERIC	Beschikbaar kasgeld
cash_pct	NUMERIC	Kaspercentage
regime	VARCHAR	Risk-on / Risk-off
profile_id	BIGINT	Risicoprofiel FK

Stream 2: Holdings Data

Actuele posities per risicoprofiel.

Veld	Type	Beschrijving
ticker	VARCHAR	Aandelensymbool
shares	NUMERIC	Aantal aandelen
avg_cost	NUMERIC	Gemiddelde instapprijs
current_value	NUMERIC	Huidige waarde
weight_pct	NUMERIC	Gewicht in portefeuille
profile_id	BIGINT	Risicoprofiel FK

Stream 3: Trades Data

Handelsgeschiedenis voor transparantie en reconciliatie.

Veld	Type	Beschrijving
date	DATE	Handelsdatum
action	VARCHAR	BUY, SELL, SHORT_ENTRY, etc.
ticker	VARCHAR	Aandelensymbool
shares	NUMERIC	Aantal aandelen
price	NUMERIC	Uitvoeringsprijs
reason	VARCHAR	EXIT_RANK, EXIT_MA, etc.
profile_id	BIGINT	Risicoprofiel FK

Flex cloud schema (7 tabellen)

Tabel	Bron	Sync-frequentie	Doel
`engine_equity_snapshots`	Equity stream	Wekelijks	Equity-curve per profiel
`engine_holdings`	Holdings stream	Wekelijks	Actuele posities
`engine_trades`	Trades stream	Wekelijks	Handelsgeschiedenis
`reconciliation_log`	Flex API + Engine	Dagelijks	3-tier vergelijking
`risk_profiles`	Configuratie	Bij wijziging	Profielparameters
`nav_history`	Berekening	Maandelijks	NAV per profiel per maand
`unit_transactions`	Fondstransacties	Bij gebeurtenis	Onveranderlijk unit-grootboek

Ingestion pipeline (3 Artisan commands)

De data-synchronisatie loopt via drie Laravel Artisan commands:

1. `etl:sync-equity`

Synchroniseert wekelijkse equity-snapshots van engine-output naar engine_equity_snapshots.

Methode: Truncate-and-reload (idempotent)
Locking: pg_advisory_lock(1001) voorkomt gelijktijdige ETL en Laravel-toegang
Bulk insert: psycopg3 COPY protocol voor snelle PostgreSQL-insert

2. `etl:sync-holdings`

Synchroniseert actuele posities naar engine_holdings.

Methode: Truncate-and-reload
Timing: Na wekelijkse rebalance

3. `etl:sync-trades`

Synchroniseert nieuwe trades naar engine_trades.

Methode: Append-only (nieuwe trades worden toegevoegd)
Deduplicatie: Op basis van datum + ticker + actie combinatie

3-tier reconciliatie

Tier	Drempel	Actie
OK	< 0,1% verschil	Automatisch goedgekeurd
Waarschuwing	0,1% - 1,0%	Review vereist, NAV publiceerbaar
Fout	> 1,0%	Blokkeert NAV-publicatie

De reconciliatie vergelijkt drie bronnen:

Engine-waarde — berekend uit engine equity-snapshots
IBKR-waarde — opgevraagd via Flex API
Cloud-waarde — opgeslagen in de database

IBKR is de primaire bron (belt), de engine fungeert als sanity check (suspenders).

ETL veiligheidsmechanismen

Atomiciteit en Foutafhandeling

Advisory locking: pg_advisory_lock(1001) zorgt ervoor dat ETL en Laravel-queries niet tegelijk op dezelfde tabellen draaien
Transactie-scope: Elke sync draait in een enkele database-transactie. Gaat er iets mis, dan draait de hele sync terug
Idempotentie: Truncate-and-reload betekent dat elke sync-run hetzelfde resultaat geeft, ongeacht hoe vaak je hem uitvoert
Logging: Elke sync-run krijgt een logregel met tijdstempel, aantal rijen en eventuele fouten

Wekelijkse Batch-Sync Rationale

De sync volgt de wekelijkse rebalance-cadans van System 1. Dat is een bewuste keuze:

Ontmoedigt dagelijks portfolio-checken
Past beter bij hoe beleggers in weken en maanden denken
Houdt serverbelasting en databasekosten laag

Python CLI specificatie

ETL Command-Line Interface

De ETL-synchronisatie wordt aangestuurd via een Python CLI (Click-gebaseerd):

helios etl sync --target equity    # Sync equity-snapshots
helios etl sync --target holdings  # Sync holdings
helios etl sync --target trades    # Sync trades
helios etl sync --all              # Alle streams

helios etl reconcile               # Vergelijk engine vs IBKR vs cloud
helios etl status                  # Toon laatste sync-status

De CLI leest configuratie uit settings.toml en verbindt met de cloud-database via een beveiligde connectiestring.