Files
trade-doc/trade-system-flow.html

693 lines
20 KiB
HTML

<!doctype html>
<html lang="pl">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Trade system flow</title>
<style>
:root {
--bg: #efe7db;
--paper: rgba(255, 251, 245, 0.94);
--panel: #fffdf9;
--ink: #1c1814;
--muted: #655d53;
--line: #d9ccb9;
--web: #2a6b8f;
--api: #0f6c72;
--data: #4e5968;
--chain: #b24a32;
--exec: #7b6110;
--ok: #1d6b43;
--warn: #914017;
--shadow: 0 18px 44px rgba(28, 24, 20, 0.10);
--radius: 18px;
}
* { box-sizing: border-box; }
body {
margin: 0;
color: var(--ink);
font-family: "IBM Plex Sans", "Segoe UI", sans-serif;
background:
radial-gradient(circle at top left, rgba(42, 107, 143, 0.12), transparent 28%),
radial-gradient(circle at top right, rgba(178, 74, 50, 0.12), transparent 24%),
linear-gradient(180deg, #f8f3eb 0%, var(--bg) 100%);
}
.page {
max-width: 1540px;
margin: 0 auto;
padding: 28px 18px 42px;
}
.hero,
.card,
.table-card,
.lane,
.note,
.tabs {
background: var(--paper);
border: 1px solid rgba(217, 204, 185, 0.9);
border-radius: var(--radius);
box-shadow: var(--shadow);
backdrop-filter: blur(10px);
}
.hero {
padding: 26px;
margin-bottom: 18px;
}
.eyebrow {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 6px 10px;
border-radius: 999px;
border: 1px solid rgba(28, 24, 20, 0.10);
color: var(--muted);
font-size: 12px;
font-weight: 800;
letter-spacing: 0.08em;
text-transform: uppercase;
}
h1 {
margin: 14px 0 10px;
font-size: clamp(2rem, 4vw, 3.9rem);
line-height: 0.96;
font-family: "IBM Plex Serif", Georgia, serif;
}
p {
margin: 0;
color: var(--muted);
line-height: 1.58;
}
.tabs {
display: flex;
gap: 10px;
flex-wrap: wrap;
padding: 12px;
margin-bottom: 18px;
}
.tab {
border: 1px solid var(--line);
background: #fffaf2;
border-radius: 999px;
padding: 10px 14px;
font: inherit;
font-weight: 800;
cursor: pointer;
transition: 150ms ease;
}
.tab.active,
.tab:hover {
transform: translateY(-1px);
box-shadow: 0 10px 22px rgba(28, 24, 20, 0.08);
}
.tab[data-target="overview"].active { color: var(--web); }
.tab[data-target="routes"].active { color: var(--api); }
.tab[data-target="payloads"].active { color: var(--chain); }
.view { display: none; }
.view.active { display: block; }
.lanes {
display: grid;
grid-template-columns: 1.05fr 0.9fr 0.95fr;
gap: 16px;
margin-bottom: 18px;
}
.lane {
padding: 16px;
}
.lane h2 {
margin: 0 0 6px;
font-size: 1.2rem;
font-family: "IBM Plex Serif", Georgia, serif;
}
.lane small {
display: block;
color: var(--muted);
margin-bottom: 14px;
line-height: 1.45;
}
.stack {
display: grid;
gap: 12px;
}
.card {
padding: 14px;
background: var(--panel);
border-left: 6px solid var(--line);
}
.card h3 {
margin: 0 0 6px;
font-size: 1rem;
}
.meta {
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--muted);
font-weight: 800;
margin-bottom: 8px;
}
.card.web { border-left-color: var(--web); }
.card.api { border-left-color: var(--api); }
.card.data { border-left-color: var(--data); }
.card.chain { border-left-color: var(--chain); }
.card.exec { border-left-color: var(--exec); }
.chips {
display: flex;
flex-wrap: wrap;
gap: 8px;
margin-top: 10px;
}
.chip {
display: inline-block;
padding: 4px 8px;
border-radius: 999px;
font-size: 12px;
font-weight: 700;
background: rgba(28, 24, 20, 0.06);
}
.flow {
display: grid;
gap: 14px;
margin-top: 12px;
}
.flow-row {
display: grid;
grid-template-columns: repeat(5, minmax(0, 1fr));
gap: 12px;
align-items: stretch;
}
.flow-node {
padding: 14px;
border: 1px solid var(--line);
border-radius: 14px;
background: #fffdf9;
min-height: 118px;
position: relative;
}
.flow-node strong {
display: block;
margin-bottom: 8px;
font-size: 0.98rem;
}
.arrow {
display: flex;
align-items: center;
justify-content: center;
font-size: 24px;
color: var(--muted);
font-weight: 700;
}
.table-card {
padding: 14px;
overflow: auto;
}
table {
width: 100%;
border-collapse: collapse;
min-width: 980px;
}
th,
td {
padding: 12px 10px;
border-bottom: 1px solid var(--line);
text-align: left;
vertical-align: top;
line-height: 1.45;
}
th {
font-size: 12px;
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--muted);
}
code,
pre {
font-family: "IBM Plex Mono", monospace;
}
pre {
margin: 0;
white-space: pre-wrap;
word-break: break-word;
background: rgba(28, 24, 20, 0.04);
border-radius: 12px;
padding: 14px;
line-height: 1.45;
}
.payload-grid {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 16px;
}
.note {
padding: 16px 18px;
margin-top: 18px;
}
.status {
display: inline-flex;
align-items: center;
gap: 6px;
font-size: 12px;
font-weight: 800;
padding: 4px 8px;
border-radius: 999px;
background: rgba(28, 24, 20, 0.06);
}
.ok { color: var(--ok); background: rgba(29, 107, 67, 0.10); }
.warn { color: var(--warn); background: rgba(178, 74, 50, 0.10); }
@media (max-width: 1220px) {
.lanes,
.payload-grid,
.flow-row {
grid-template-columns: 1fr;
}
.arrow {
transform: rotate(90deg);
min-height: 32px;
}
table { min-width: 720px; }
}
</style>
</head>
<body>
<div class="page">
<section class="hero">
<div class="eyebrow">Trade architecture / runtime map</div>
<h1>Skąd dane trafiają, w jakiej postaci i które endpointy naprawdę wystawiamy</h1>
<p>
Ta strona opisuje faktyczny przepływ runtime dla waszej appki: <strong>browser -> frontend -> API/Hasura -> Postgres/Redis</strong>
oraz zależności od <strong>Agave RPC</strong> i <strong>Yellowstone gRPC</strong>. To nie jest ogólny diagram architektury,
tylko mapa wejść, wyjść, formatów danych i tras HTTP/WS używanych przez produkt.
</p>
</section>
<section class="tabs">
<button class="tab active" data-target="overview">Overview</button>
<button class="tab" data-target="routes">Routes / APIs</button>
<button class="tab" data-target="payloads">Payloads / shapes</button>
</section>
<section class="view active" id="overview">
<div class="lanes">
<article class="lane">
<h2>Public web surface</h2>
<small>To widzi użytkownik i to jest jedyny realny entrypoint produktu na zewnątrz.</small>
<div class="stack">
<div class="card web">
<div class="meta">NodePort / browser entry</div>
<h3>trade-frontend</h3>
<p>Serwuje SPA, obsługuje logowanie, robi proxy do API i Hasury.</p>
<div class="chips">
<span class="chip">NodePort 30081</span>
<span class="chip">service 8081</span>
<span class="chip">/api/*</span>
<span class="chip">/graphql</span>
</div>
</div>
<div class="card web">
<div class="meta">Browser calls</div>
<h3>Frontend SPA</h3>
<p>Wykres bierze REST JSON. DLOB live bierze GraphQL WebSocket. Auth idzie przez sesję cookie.</p>
<div class="chips">
<span class="chip">GET /whoami</span>
<span class="chip">POST /auth/login</span>
<span class="chip">GET /api/v1/chart</span>
<span class="chip">WS /graphql</span>
</div>
</div>
</div>
</article>
<article class="lane">
<h2>App services in k3s</h2>
<small>Wewnętrzne usługi aplikacyjne. Tylko frontend jest dziś wystawiony na zewnątrz jako NodePort.</small>
<div class="stack">
<div class="card api">
<div class="meta">ClusterIP / app logic</div>
<h3>trade-api</h3>
<p>REST backend. Zwraca candles, przyjmuje tick ingest, zarządza tokenami.</p>
<div class="chips">
<span class="chip">ClusterIP 8787</span>
<span class="chip">/v1/chart</span>
<span class="chip">/v1/ticks</span>
<span class="chip">/v1/ingest/tick</span>
</div>
</div>
<div class="card data">
<div class="meta">ClusterIP / query plane</div>
<h3>Hasura + Postgres</h3>
<p>Frontend subskrybuje Hasurę po GraphQL WS. API czyta i zapisuje przez GraphQL do Hasury.</p>
<div class="chips">
<span class="chip">Hasura 8080</span>
<span class="chip">Postgres 5432</span>
<span class="chip">GraphQL</span>
<span class="chip">subscriptions</span>
</div>
</div>
<div class="card data">
<div class="meta">Redis-backed read side</div>
<h3>DLOB stack</h3>
<p><span class="status warn">publisher 0/1</span> <span class="status warn">server 0/1</span> bo bootstrapping zależy od zdrowego Agave RPC.</p>
<div class="chips">
<span class="chip">Redis 6379</span>
<span class="chip">dlob-server 6969</span>
<span class="chip">workers</span>
</div>
</div>
</div>
</article>
<article class="lane">
<h2>Chain and execution plane</h2>
<small>To nie jest wystawiane użytkownikowi końcowemu. To feed i write side dla botów.</small>
<div class="stack">
<div class="card chain">
<div class="meta">mevnode_sol / source of truth</div>
<h3>Agave RPC</h3>
<p>Punktowe odczyty: <code>getAccountInfo</code>, <code>getMultipleAccounts</code>, <code>getSlot</code>, <code>getHealth</code>.</p>
<div class="chips">
<span class="chip">127.0.0.1:8899</span>
<span class="chip">RPC only</span>
</div>
</div>
<div class="card chain">
<div class="meta">mevnode_sol / live feed</div>
<h3>Yellowstone gRPC</h3>
<p>Pushowy stream kont, slotów i transakcji po <code>wg0</code>.</p>
<div class="chips">
<span class="chip">10.91.0.1:10000</span>
<span class="chip">token auth</span>
</div>
</div>
<div class="card exec">
<div class="meta">future execution split</div>
<h3>tx-router / TPU / Jito</h3>
<p>To jest write path. Nie mylić z Yellowstone, który jest tylko read streamem.</p>
</div>
</div>
</article>
</div>
<div class="table-card">
<div class="meta">End-to-end runtime flow</div>
<div class="flow">
<div class="flow-row">
<div class="flow-node"><strong>1. Browser</strong>Użytkownik otwiera SPA i trzyma sesję cookie.</div>
<div class="arrow"></div>
<div class="flow-node"><strong>2. trade-frontend</strong>Serwuje UI i robi reverse proxy do <code>/api</code> i <code>/graphql</code>.</div>
<div class="arrow"></div>
<div class="flow-node"><strong>3. trade-api / Hasura</strong>REST dla chartów, GraphQL WS dla live DLOB.</div>
</div>
<div class="flow-row">
<div class="flow-node"><strong>4. Postgres / Redis</strong>Trwały stan i szybki stan pośredni.</div>
<div class="arrow"></div>
<div class="flow-node"><strong>5. DLOB workers</strong>Przeliczają depth, slippage, orderbook views.</div>
<div class="arrow"></div>
<div class="flow-node"><strong>6. Agave / Yellowstone</strong>RPC do odczytów punktowych, gRPC do streamu live.</div>
</div>
</div>
</div>
<div class="note">
<p>
Najważniejszy podział: <strong>chart path = REST JSON przez trade-api</strong>, a <strong>DLOB live = GraphQL WS przez Hasurę</strong>.
To oznacza, że nie cały frontend jedzie jednym typem transportu. Produkt ma dwa równoległe read pathy.
</p>
</div>
</section>
<section class="view" id="routes">
<div class="table-card">
<table>
<thead>
<tr>
<th>Surface</th>
<th>Endpoint</th>
<th>Transport</th>
<th>Input</th>
<th>Output</th>
<th>Where it goes</th>
</tr>
</thead>
<tbody>
<tr>
<td>Frontend</td>
<td><code>GET /whoami</code></td>
<td>HTTP JSON</td>
<td>cookie session</td>
<td><code>{ ok, user, mode }</code></td>
<td>handled directly by <code>trade-frontend</code></td>
</tr>
<tr>
<td>Frontend</td>
<td><code>POST /auth/login</code></td>
<td>HTTP JSON/form</td>
<td><code>username</code>, <code>password</code></td>
<td><code>{ ok, user }</code> + session cookie</td>
<td>handled directly by <code>trade-frontend</code></td>
</tr>
<tr>
<td>Frontend</td>
<td><code>POST /auth/logout</code></td>
<td>HTTP JSON</td>
<td>session cookie</td>
<td><code>{ ok: true }</code></td>
<td>handled directly by <code>trade-frontend</code></td>
</tr>
<tr>
<td>Frontend proxy</td>
<td><code>/api/*</code></td>
<td>HTTP</td>
<td>browser request, frontend injects read token</td>
<td>proxied API response</td>
<td><code>trade-api:8787</code></td>
</tr>
<tr>
<td>Frontend proxy</td>
<td><code>/graphql</code></td>
<td>HTTP GraphQL</td>
<td>GraphQL query/mutation</td>
<td>GraphQL response</td>
<td><code>hasura:8080/v1/graphql</code></td>
</tr>
<tr>
<td>Frontend proxy</td>
<td><code>WS /graphql</code></td>
<td>GraphQL WebSocket</td>
<td>subscription payload</td>
<td>live subscription frames</td>
<td><code>hasura:8080/v1/graphql</code></td>
</tr>
<tr>
<td>API</td>
<td><code>GET /v1/chart</code></td>
<td>HTTP JSON</td>
<td><code>symbol</code>, <code>tf</code>, <code>limit</code>, optional <code>source</code></td>
<td>candles + indicators + flow rows</td>
<td>Hasura function <code>get_drift_candles</code> + table <code>drift_ticks</code></td>
</tr>
<tr>
<td>API</td>
<td><code>POST /v1/ingest/tick</code></td>
<td>HTTP JSON</td>
<td>tick payload</td>
<td><code>{ ok, id }</code></td>
<td>writes tick through Hasura into DB</td>
</tr>
<tr>
<td>API</td>
<td><code>GET /v1/ticks</code></td>
<td>HTTP JSON</td>
<td><code>symbol</code>, optional <code>source</code>, <code>limit</code>, <code>from</code>, <code>to</code></td>
<td>tick list</td>
<td>reads <code>drift_ticks</code> through Hasura</td>
</tr>
<tr>
<td>API admin</td>
<td><code>POST /v1/admin/tokens</code></td>
<td>HTTP JSON</td>
<td>name, scopes</td>
<td>new API token</td>
<td>stored in DB via Hasura</td>
</tr>
<tr>
<td>API admin</td>
<td><code>POST /v1/admin/tokens/revoke</code></td>
<td>HTTP JSON</td>
<td>token id</td>
<td>revocation status</td>
<td>updates token row in DB</td>
</tr>
<tr>
<td>Chain read</td>
<td><code>Agave RPC</code></td>
<td>JSON-RPC</td>
<td>account/state requests</td>
<td>point reads</td>
<td><code>mevnode_sol</code></td>
</tr>
<tr>
<td>Chain live</td>
<td><code>Yellowstone gRPC</code></td>
<td>gRPC streaming</td>
<td>subscription config + token</td>
<td>account/slot/tx stream</td>
<td><code>mevnode_sol</code></td>
</tr>
</tbody>
</table>
</div>
</section>
<section class="view" id="payloads">
<div class="payload-grid">
<div class="table-card">
<div class="meta">Chart response</div>
<pre>{
"ok": true,
"symbol": "SOL-PERP",
"tf": "1m",
"bucketSeconds": 60,
"candles": [
{
"time": 1710000000,
"open": 132.1,
"high": 133.2,
"low": 131.8,
"close": 132.9,
"volume": 412,
"oracle": 132.7,
"flow": { "up": 0.46, "down": 0.41, "flat": 0.13 },
"flowRows": [1, 1, 0, -1],
"flowMoves": [0.2, 0.1, 0, 0.3]
}
],
"indicators": {
"sma20": [{ "time": 1710000000, "value": 131.4 }],
"ema20": [{ "time": 1710000000, "value": 131.8 }],
"bb20": { "upper": [], "lower": [], "mid": [] },
"rsi14": [],
"macd": { "macd": [], "signal": [] }
}
}</pre>
</div>
<div class="table-card">
<div class="meta">Tick ingest body</div>
<pre>{
"ts": "2026-03-13T11:20:00.000Z",
"market_index": 0,
"symbol": "SOL-PERP",
"oracle_price": "132.70",
"mark_price": "132.91",
"oracle_slot": 406125100,
"source": "drift",
"raw": {
"provider": "internal"
}
}</pre>
</div>
<div class="table-card">
<div class="meta">GraphQL DLOB subscriptions</div>
<pre>subscription DlobStats($market: String!) {
dlob_stats_latest(where: {market_name: {_eq: $market}}, limit: 1) {
market_name
mark_price
oracle_price
best_bid_price
best_ask_price
mid_price
spread_abs
spread_bps
depth_bid_usd
depth_ask_usd
imbalance
updated_at
}
}</pre>
</div>
<div class="table-card">
<div class="meta">L2 payload shape</div>
<pre>{
"market_name": "SOL-PERP",
"bids": [
{ "price": 132910000, "size": 2500000000 }
],
"asks": [
{ "price": 132930000, "size": 1700000000 }
],
"updated_at": "2026-03-13T11:20:01.000Z"
}
Frontend przelicza to przez:
- pricePrecision = 1_000_000
- basePrecision = 1_000_000_000</pre>
</div>
</div>
<div class="note">
<p>
Krytyczne rozróżnienie: <strong>DLOB live nie idzie z REST API</strong>. DLOB do UI idzie przez <strong>Hasura GraphQL subscriptions</strong>,
a chart przez <strong>REST JSON</strong> z <code>trade-api</code>. To są dwa osobne transporty, dwa osobne modele danych i dwa osobne źródła opóźnień.
</p>
</div>
</section>
</div>
<script>
const tabs = [...document.querySelectorAll('.tab')];
const views = [...document.querySelectorAll('.view')];
tabs.forEach((tab) => {
tab.addEventListener('click', () => {
const target = tab.dataset.target;
tabs.forEach((x) => x.classList.toggle('active', x === tab));
views.forEach((view) => view.classList.toggle('active', view.id === target));
});
});
</script>
</body>
</html>