> For the complete documentation index, see [llms.txt](https://docs.cafx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cafx.io/architecture/architecture-pivot-draft.md). # Architecture Overview ## What We Have Now Two systems that run separately and then get compared: 1. **ML Model** — 6 LightGBM models (one per token cluster). Looks at price data, BTC correlation, volatility regime. Outputs a direction (Long/Short/Neutral) and a confidence probability. Threshold is 60%. 2. **Trend Analyzer** — Rust-native. 5 weighted indicators (EMA, ADX, MACD, RSI, Bollinger). Outputs a direction and confidence level (High/Medium/Low). Runs every 5 minutes. 3. **Arbitration Gate** — Compares both outputs. If they agree → trade. If they disagree → Defensive Standby (pause new entries, protect existing positions with stop-losses). **Grid placement today:** When a trade is approved, the grid is built around the **current price** using ATR to set upper/lower bounds, then levels are spaced evenly (linear) or geometrically within that range. There's no structural reasoning behind *where* the grid sits — it's just "current price ± some volatility buffer." **SMC exists but is isolated:** There's already an SMC engine in the limit bot (`smc.rs`) that detects order blocks, demand/supply zones, and liquidity zones with strength scores and risk assessment. But it's completely separate from the grid bot — the grid bot doesn't use it. ``` Model ──→ ┐ ├──→ Do they agree? ──→ Yes: Trade (grid around current price) / No: Standby Trend ──→ ┘ SMC ──→ (only used by limit bot, grid bot ignores it) ``` ## What's Wrong With It **The model predicts direction without knowing if conditions support it.** It says "go long" based on patterns it learned from historical data, but it doesn't check whether the market right now actually has the setup for that long to work out. The trend analyzer catches some of this by disagreeing, but that's a blunt fix — it just blocks the trade entirely instead of informing the decision. **Both systems work blind to each other.** The model doesn't know what the trend analyzer sees. The trend analyzer doesn't know what the model thinks. They just vote independently and we check if they happen to agree. That's wasteful — when they disagree we sit out entirely, even if one of them has a strong read. **The model treats all markets the same way mechanically.** The cluster system helps (different model per cluster), but the model still doesn't account for real-time context like news, sentiment, or how price is actually reacting at key levels right now. It's pattern-matching on history. **60% confidence is too low.** We're entering trades where the model is barely more confident than a coin flip. That generates volume but not quality. **Grids are placed blindly.** When a trade fires, the grid goes around whatever the current price is, padded by ATR. There's no consideration of where demand/supply zones actually are, where order blocks sit, or where liquidity pools exist. We already have an SMC engine that finds these zones — it just isn't connected to the grid bot. So we're entering the market at arbitrary levels instead of structurally significant ones. ## What Changes Three things: (1) SMC identifies zones and grids are placed around them, (2) the model is triggered by price approaching those zones instead of running on a timer, and (3) the model watches price action at the zone before giving a signal that gets checked against the trend analyzer. ``` ┌──────────────────────────────────────────────────────────────┐ │ SETUP PHASE │ │ │ │ TA / SMC ──→ Identify demand/supply zones, order blocks, │ │ liquidity pools │ │ ──→ Place grids around those zones (dormant) │ └──────────────────────────────────┬───────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ TRIGGER │ │ │ │ Price approaches a zone ──→ Model wakes up │ │ │ └──────────────────────────────────┬───────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ MODEL WATCHES │ │ │ │ Model monitors price action at the zone: │ │ • Fractal structure breaks │ │ • Other confirmation parameters │ │ • Zone context from SMC (zone type, strength) │ │ • Trend context from Trend Analyzer │ │ │ │ Model produces signal + confidence │ └──────────────────────────────────┬───────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ GATING (same as today) │ │ │ │ Model signal ◄──► Trend Analyzer signal │ │ │ │ Agree + ≥ 70% confidence ──→ Activate grid orders │ │ Disagree or < 70% ──→ Grid stays dormant │ └──────────────────────────────────────────────────────────────┘ ``` **SMC runs first and sets the stage.** It identifies structurally meaningful zones — demand, supply, order blocks, liquidity. Grids get placed around those zones but stay dormant. No orders go to the exchange yet. **The model is event-driven, not timer-driven.** Today the model runs every hour on a clock. In the new design, price approaching an SMC zone is what triggers the model. The model doesn't waste cycles evaluating when price is in no-man's-land. **The model watches before signaling.** When triggered, the model doesn't instantly produce a direction. It monitors price action at the zone — looking for fractal structure breaks and other confirmation signals. SMC zone data (type, strength) and trend analyzer output both feed into the model as context for this assessment. **The gating stays.** Model signal gets checked against the trend analyzer, same as today. Both need to agree. If they don't, the grid stays dormant. If they do and confidence is ≥ 70%, the grid orders activate. ## What It Means **Fewer trades.** The model only fires when price hits a zone, and even then it watches and waits for confirmation before signaling. Most zone approaches won't produce a signal. That's the point. **Better entries.** When we do trade, the grid is on a structurally meaningful level, the model saw a fractal structure break at that level, and the trend analyzer agrees with the direction. That's three layers of confirmation before a single order activates. **The model changes fundamentally.** Today it runs on a clock every hour and predicts direction from features. In the new design it's event-triggered, zone-aware, and watches real-time price action for structural confirmation before producing a signal. Different trigger, different inputs, different behavior. All 6 cluster models need retraining. **Grids exist before trades do.** Grids are pre-positioned around SMC zones and sit dormant. They're infrastructure waiting for a signal, not a reaction to a signal. This inverts the current flow where the signal comes first and the grid is built after. **Sentiment/news is not day-one.** No pipeline for it exists today. The core changes can ship without it. Sentiment comes later. ## Phasing --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cafx.io/architecture/architecture-pivot-draft.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.