docs(snapshot): sync workspace documentation

2026-03-29 13:14:30 +02:00
parent 93a6e4aa2f
commit 0d3d110026
37 changed files with 8500 additions and 123 deletions
--- a/economic-markers-k3s.md
+++ b/economic-markers-k3s.md
@@ -0,0 +1,533 @@
+# Economic Markers In K3s
+
+## Cel
+
+Chcemy dodawac markery ekonomiczne i tradingowe jako osobne komponenty runtime na `mevnode_bot`, bez mieszania ich z samym orderbookiem i bez bezposredniego odpytywania kazdego markera z frontendu.
+
+Docelowy model:
+
+`worker -> Postgres -> Hasura/API -> visualizer`
+
+To ma byc warstwa:
+
+- szybka do rozwijania
+- niezalezna per marker
+- latwa do obserwacji i debugowania
+- bez ryzyka, ze jeden eksperymentalny marker psuje caly runtime
+
+## Zasada architektoniczna
+
+Markery liczymy w osobnych kontenerach na `k3s`, ale nie wystawiamy ich bezposrednio do UI.
+
+Kazdy marker:
+
+1. czyta dane z juz istniejacego runtime:
+   - `Hasura`
+   - `Postgres`
+   - `Redis`
+   - opcjonalnie `trade-api`
+   - opcjonalnie bezposrednio `mevnode_sol RPC`, jesli marker naprawde tego potrzebuje
+
+2. liczy wlasny sygnal
+
+3. zapisuje wynik do `Postgresa`
+
+4. `Hasura` trackuje tabele markerow
+
+5. `visualizer` rysuje:
+   - overlay na chart
+   - osobny panel pod chartem
+   - badge / regime / warning nad marketem
+
+Frontend nie powinien znac topologii workerow.
+
+## Dlaczego osobne kontenery
+
+To daje kilka korzysci:
+
+- izolacja awarii
+- latwe rollouty
+- rozne cadence per marker
+- mozliwosc wlaczania / wylaczania markerow niezaleznie
+- prostszy profiling CPU i memory
+- latwiejszy eksperyment workflow
+
+Dobry podzial:
+
+- `fast markers`
+  - 200-500 ms
+  - mikrostruktura
+  - imbalance
+  - orderbook slope
+  - spread regime
+
+- `medium markers`
+  - 1-5 s
+  - funding pressure
+  - basis
+  - depth depletion
+  - oracle divergence
+
+- `slow markers`
+  - 10-60 s
+  - volatility regime
+  - realized vol
+  - trend regime
+  - event calendars
+
+## Rekomendowany model danych
+
+Nie robimy osobnej tabeli per kazdy marker.
+
+Na start lepszy jest wspolny model:
+
+### 1. `market_markers_latest`
+
+Jedna tabela z najnowsza wartoscia markera.
+
+Przyklad kolumn:
+
+- `source`
+- `market_name`
+- `marker_name`
+- `ts`
+- `value_num`
+- `value_text`
+- `value_bool`
+- `band`
+- `confidence`
+- `severity`
+- `meta jsonb`
+- `updated_at`
+
+Klucz logiczny:
+
+`(source, market_name, marker_name)`
+
+To jest warstwa pod:
+
+- karty market details
+- badge typu `risk on`, `thin book`, `high dislocation`
+- ostatni stan markera
+
+### 2. `market_markers_ts`
+
+Historia timeseries dla markerow.
+
+Przyklad kolumn:
+
+- `event_ts`
+- `id`
+- `source`
+- `market_name`
+- `marker_name`
+- `value_num`
+- `value_text`
+- `value_bool`
+- `band`
+- `confidence`
+- `severity`
+- `meta jsonb`
+- `inserted_at`
+
+To jest warstwa pod:
+
+- overlaye na chart
+- osobne panele
+- replay
+- debug
+- porownanie markerow w czasie
+
+### 3. `market_marker_events`
+
+Opcjonalna tabela tylko dla zmian stanu i alertow.
+
+Przyklad:
+
+- `event_ts`
+- `source`
+- `market_name`
+- `marker_name`
+- `event_type`
+- `prev_value`
+- `next_value`
+- `severity`
+- `meta`
+
+To jest pod:
+
+- timeline alertow
+- debug strategy
+- feed zdarzen na UI
+
+## Typy markerow
+
+Najlepiej od razu rozdzielic markery na klasy.
+
+### Overlay markers
+
+To sa serie rysowane bezposrednio na wykresie ceny:
+
+- fair value
+- local VWAP
+- short-term imbalance line
+- oracle divergence bands
+- liquidation zones
+- micro support / resistance
+
+Dane:
+
+- `value_num`
+- opcjonalnie `band`
+- opcjonalnie `meta.upper`, `meta.lower`
+
+### Panel markers
+
+To sa osobne serie pod wykresem:
+
+- spread bps
+- imbalance
+- depth asymmetry
+- book velocity
+- trade aggression
+- realized vol
+
+### State markers
+
+To sa dyskretne stany:
+
+- `trend_up`
+- `range`
+- `high_risk`
+- `thin_liquidity`
+- `event_window`
+
+Tu zwykle:
+
+- `value_text`
+- `value_bool`
+- `severity`
+- `confidence`
+
+## Rekomendowane markery na start
+
+Pierwszy pakiet powinien byc maly i praktyczny.
+
+### Marker 1. `oracle_dislocation_bps`
+
+Liczy:
+
+`(mark - oracle) / oracle * 10_000`
+
+Cel:
+
+- pokazac odklejenie od oracle
+- ostrzegac, kiedy orderbook/mark zaczyna byc sztucznie przesuniety
+
+Prezentacja:
+
+- panel pod chartem
+- badge nad marketem po przekroczeniu progow
+
+### Marker 2. `top12_imbalance`
+
+Liczy:
+
+`(bid_usd - ask_usd) / (bid_usd + ask_usd)`
+
+na poziomach zblizonych do tego, co pokazuje orderbook UI
+
+Cel:
+
+- prosty sygnal przewagi strony
+- zgodnosc z tym, co trader widzi na ekranie
+
+Prezentacja:
+
+- panel
+- opcjonalnie mini sparkline obok orderbooka
+
+### Marker 3. `spread_regime`
+
+Liczy stan:
+
+- `tight`
+- `normal`
+- `wide`
+
+na bazie `spread_bps`
+
+Cel:
+
+- szybki filtr, czy rynek nadaje sie do wejscia
+
+Prezentacja:
+
+- badge w market details
+
+### Marker 4. `depth_depletion`
+
+Liczy:
+
+- spadek plynnosci top-of-book vs rolling baseline
+
+Cel:
+
+- wykrywanie, ze ksiazka staje sie pusta zanim ruch przyspieszy
+
+Prezentacja:
+
+- panel
+- alert event
+
+### Marker 5. `micro_vol_regime`
+
+Liczy:
+
+- rolling realized volatility na `1s` / `5s` / `1m`
+
+Cel:
+
+- odroznic spokojny market od marketu o zbyt duzym noise
+
+Prezentacja:
+
+- panel pod chartem
+
+## K3s deployment model
+
+Na start proponuje namespace `trade`.
+
+Kazdy marker to osobny `Deployment`, ale z tym samym kontraktem runtime.
+
+Przyklad nazw:
+
+- `marker-oracle-dislocation`
+- `marker-top12-imbalance`
+- `marker-spread-regime`
+- `marker-depth-depletion`
+- `marker-micro-vol`
+
+Kazdy deployment:
+
+- `replicas: 1`
+- `ConfigMap` dla parametrow
+- `Secret` tylko jesli musi czytac cos wrazliwego
+- write tylko do Postgresa / Hasury
+
+Nie robimy dla nich publicznych `Service`, jesli nie maja HTTP health/debug endpointu.
+
+Jesli worker ma HTTP:
+
+- tylko `ClusterIP`
+- endpointy:
+  - `/healthz`
+  - `/metrics`
+  - `/debug/state`
+
+## Read path dla markerow
+
+Na start marker powinien czytac glownie z durable read modelu:
+
+- `dlob_hot_snapshot_latest`
+- `dlob_hot_derived_latest`
+- `dlob_hot_derived_ts`
+- `dlob_all_derived_latest`
+- `dlob_all_derived_ts`
+- `dlob_stats_latest`
+- `dlob_depth_bps_latest`
+- `dlob_slippage_latest`
+
+To daje:
+
+- prostszy kod
+- mniej zaleznosci
+- zgodnosc z tym, co widzi UI
+
+Bezposredni odczyt z `mevnode_sol RPC` ma sens tylko wtedy, gdy:
+
+- marker potrzebuje point read accountow
+- marker potrzebuje szybszego feedu niz Postgres
+- marker ma byc trading-critical, a nie tylko UI/debug
+
+## Write path dla markerow
+
+Najbezpieczniejszy model:
+
+- worker liczy marker
+- worker robi `upsert` do `market_markers_latest`
+- worker robi `insert` do `market_markers_ts`
+
+Opcjonalnie:
+
+- worker emituje event do `market_marker_events`, gdy zmienia sie `band` albo `severity`
+
+## Hasura
+
+Hasura powinna trackowac:
+
+- `market_markers_latest`
+- `market_markers_ts`
+- `market_marker_events`
+
+Public read:
+
+- tylko wybrane kolumny
+- filtr po `market_name`
+- opcjonalnie filtr po `marker_name`
+
+To pozwala frontendowi robic:
+
+- subskrypcje latest
+- query historii per marker
+- timeline eventow
+
+## Visualizer
+
+Visualizer powinien miec trzy tryby prezentacji markerow.
+
+### 1. Overlay na chart
+
+Dla markerow typu line / band:
+
+- `fair value`
+- `oracle dislocation bands`
+- `micro support`
+
+UI:
+
+- toggle per marker
+- wspolny selector `Indicators / Markers`
+
+### 2. Panele pod chartem
+
+Dla markerow oscylatorowych:
+
+- imbalance
+- spread bps
+- micro vol
+
+UI:
+
+- jeden panel moze pokazywac kilka serii
+- albo osobne male panele
+
+### 3. Market badges
+
+Dla stanow:
+
+- `thin book`
+- `wide spread`
+- `high dislocation`
+- `event risk`
+
+UI:
+
+- nad chartem
+- nad orderbookiem
+- w market details
+
+## Co jest trading-critical, a co research-only
+
+Trzeba to rozdzielic od poczatku.
+
+### Trading-critical
+
+Markery, ktore moga wejsc do decyzji runtime:
+
+- dislocation
+- spread regime
+- top book depletion
+- aggressive imbalance
+
+Dla nich:
+
+- niski latency
+- jasne SLA
+- monitoring
+- alerting
+
+### Research-only
+
+Markery, ktore sa glownie dla obserwacji:
+
+- eksperymentalne composite scores
+- event overlays
+- egzotyczne oscylatory
+
+Dla nich:
+
+- moga byc liczone wolniej
+- moga siedziec w osobnych workerach
+- nie powinny blokowac runtime
+
+## Rekomendowany rollout
+
+### Etap 1
+
+Zrobic wspolne tabele:
+
+- `market_markers_latest`
+- `market_markers_ts`
+
+oraz trackowanie w Hasurze.
+
+### Etap 2
+
+Uruchomic 2 pierwsze markery:
+
+- `oracle_dislocation_bps`
+- `top12_imbalance`
+
+### Etap 3
+
+Dorysowac to w visualizerze:
+
+- 1 overlay
+- 1 panel
+- 1 badge
+
+### Etap 4
+
+Dopiero potem dodawac kolejne markery.
+
+Nie zaczynac od 10 workerow naraz.
+
+## Kontrakt implementacyjny workerow
+
+Kazdy worker powinien miec:
+
+- jeden glowny loop
+- czytelny input set
+- czytelny output set
+- idempotentny write
+- logging per cycle
+- proste metryki Prometheus
+
+Minimum metryk:
+
+- `marker_compute_duration_ms`
+- `marker_last_success_ts`
+- `marker_rows_written_total`
+- `marker_failures_total`
+- `marker_input_staleness_ms`
+
+## Moja rekomendacja dla tego projektu
+
+Na teraz najlepszy model to:
+
+1. osobne workery markerow w `k3s`
+2. wspolne tabele `latest + ts`
+3. `Hasura` jako read layer
+4. `visualizer` jako warstwa renderu
+5. `mevnode_sol RPC` tylko dla markerow, ktore naprawde musza wyjsc poza aktualny read model
+
+To jest wystarczajaco porzadne pod trade, a jednoczesnie nadal lekkie i szybkie do rozwijania.
+
+## Co warto zrobic jutro
+
+1. Dodac SQL dla `market_markers_latest` i `market_markers_ts`.
+2. Doliczyc pierwszy marker `oracle_dislocation_bps`.
+3. Doliczyc drugi marker `top12_imbalance`.
+4. Wystawic obie serie przez Hasure.
+5. Narysowac je w visualizerze jako proof of workflow.