trade-frontend/doc/k3s-runtime-map.md

k3s runtime map (VPS qstack) — co działa i po co

Ten dokument opisuje aktualny runtime na VPS (k3s) dla projektu trade: jakie komponenty działają w klastrze, jak płynie dane oraz które tabele/metrki są “źródłem prawdy” dla UI.

Zakładamy namespace: trade-staging.

TL;DR (logika)

• Dane są zbierane i liczone na backendzie (k3s).
• UI (trade-frontend) tylko wizualizuje i proxy’uje ruch (API + GraphQL + WS).
• Hasura to jedyny GraphQL/WS na “metrics/live” (subscriptions).
• Postgres/Timescale trzyma:
  • ticki (drift_ticks) + candles (funkcja get_drift_candles)
  • “latest” warstw DLOB (dlob_*_latest)
  • (opcjonalnie) historię warstw (dlob_*_ts)

Mapa (ruch z zewnątrz)

Internet
  |
  v
Ingress/Traefik
  |
  +--> trade-frontend   (https://trade.mpabi.pl)
  |       - /api        -> trade-api
  |       - /graphql    -> hasura
  |       - /graphql-ws -> hasura (WS subscriptions; protokół graphql-ws)
  |
  +--> (opcjonalnie inne ingressy w tym samym klastrze)

trade-frontend (UI + reverse-proxy)

• Rola: UI + proxy do usług w klastrze.
• Dlaczego: przeglądarka nie dostaje sekretów; token read jest wstrzykiwany server‑side, a WS działa przez proxy.
• Wejście: HTTP/WS od użytkownika.
• Wyjście:
  • /api/* → trade-api
  • /graphql (HTTP) → hasura
  • /graphql-ws (WS) → hasura

Mapa (dane rynkowe — ticki / candles)

Solana RPC/WS (zewn.)
  |
  v
trade-ingestor
  |
  v
trade-api  -> Postgres/Timescale (drift_ticks)
  |
  +--> /v1/chart (candles + wskaźniki liczone na backendzie)
  |
  v
Hasura (GraphQL query/subscriptions dla wybranych tabel)

trade-ingestor

• Rola: pobiera dane (oracle/mark) i wysyła ticki do API.
• Wyjście: ticki zapisane do drift_ticks przez trade-api.

trade-api

• Rola: API dla UI i algów (healthz, ticks, chart).
• DB: zapis do drift_ticks.
• Agregacje: candles (get_drift_candles) + wskaźniki (backend).

Mapa (DLOB — orderbook + metryki warstw)

Solana RPC/WS (zewn.)
  |
  v
dlob-publisher  ---->  dlob-redis  <----  dlob-server (/l2, /l3)
                                \
                                 \ (opcjonalne źródło L2)
                                  v
                            dlob-worker (kolektor L2)
                                  |
                                  v
                         Postgres/Hasura: dlob_l2_latest + dlob_stats_latest
                                  |
                     +------------+------------+
                     |                         |
                     v                         v
          dlob-depth-worker            dlob-slippage-worker
          (bands ±bps)                (impact vs size USD)
                     |                         |
                     v                         v
   Postgres/Hasura: dlob_depth_bps_latest   Postgres/Hasura: dlob_slippage_latest
                     |
                     v
             (opcjonalnie) dlob-ts-archiver
                     |
                     v
   Postgres/Timescale: dlob_stats_ts / dlob_depth_bps_ts / dlob_slippage_ts

dlob-publisher

• Rola: utrzymuje “żywy” DLOB (on‑chain) i publikuje snapshoty do Redis.
• Wejście: Solana RPC/WS.
• Wyjście: publikacja do dlob-redis.

dlob-redis

• Rola: cache/pubsub pomiędzy publisherem i serwerem HTTP.

dlob-server

• Rola: serwuje REST /l2 i /l3 na podstawie cache Redis (do debugowania i/lub jako źródło L2).

dlob-worker (kolektor L2 + “basic stats”)

• Rola: pobiera snapshoty L2 i liczy podstawowe metryki (dlob_stats_latest).
• Źródło L2: w praktyce:
  • albo zewnętrzne https://dlob.drift.trade/l2
  • albo wewnętrzne http://dlob-server:6969/l2 (jeśli tak ustawione)
• Zapis do tabel:
  • dlob_l2_latest (raw L2)
  • dlob_stats_latest (bid/ask/mid/spread/depth/imbalance)

dlob-depth-worker (depth bands ±bps)

• Rola: liczy płynność w pasmach ±bps wokół mid.
• Źródło: dlob_l2_latest
• Zapis: dlob_depth_bps_latest (klucz: market_name + band_bps)

dlob-slippage-worker (slippage vs size)

• Rola: symuluje market fill po L2 dla zadanych rozmiarów (USD) i liczy impact_bps.
• Źródło: dlob_l2_latest
• Zapis: dlob_slippage_latest (klucz: market_name + side + size_usd)

dlob-ts-archiver (historia warstw)

• Rola: zapisuje “timeline” dla warstw do hypertabli Timescale (historia pod UI).
• Źródło: dlob_stats_latest, dlob_depth_bps_latest, dlob_slippage_latest
• Zapis: dlob_stats_ts, dlob_depth_bps_ts, dlob_slippage_ts
• Retencja (startowo): ~7 dni (policy w Timescale).

Co UI realnie czyta (dla “nowych funkcji”)

• live/subscriptions:
  • dlob_stats_latest
  • dlob_depth_bps_latest
  • dlob_slippage_latest
• (jeśli dołączymy w UI wykres “historia”):
  • dlob_stats_ts
  • dlob_depth_bps_ts
  • dlob_slippage_ts

Najczęstsze miejsca problemów (diagnostyka)

• Jeśli UI nie pokazuje warstw:
  • sprawdź czy Hasura trackuje tabele i ma public select (bootstrap job),
  • sprawdź, czy workery odświeżają updated_at w dlob_*_latest.
• Jeśli dlob-worker loguje 503:
  • to zwykle problem na ścieżce DLOB_HTTP_URL (upstream/LB/IPv6) — wtedy przełącz na http://dlob-server:6969.
• Jeśli WS subscriptions nie łączą:
  • sprawdź proxy /graphql-ws w trade-frontend i origin/CORS w Hasurze.