> ## Documentation Index
> Fetch the complete documentation index at: https://uncoded.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Modules Overview — How They Work Together
> A clear, conceptual map of the six unCoded modules and the operator workflow that connects them.
**This page is the conceptual mental model.** Once you have it, the rest of the documentation maps cleanly. Read this before you read any module deep-dive — they will all reference these roles and flows.
## The six modules and their roles
unCoded is built around the principle of **separation of concerns**: each module owns one well-defined job, communicates with the others through clean contracts, and can be developed, restarted, or replaced independently. This is what makes the system robust, observable, and operationally simple.
**The execution engine.** The only component with authority to send a real order to your exchange. Reads your active configuration and turns intent into actual buys and sells, monitors fills, manages positions through to closure.
**The strategy authoring environment AND live evaluation engine.** Where you compose strategies visually, preview them on history, and — once started — where they actually run live, evaluating market data on a schedule and emitting signals when triggers fire.
**The integration layer for incoming signals.** Receives webhook signals from the SignalEditor's running strategies AND from external sources (TradingView, custom scripts), validates them against your shared secret, and translates them into configuration updates the TradingBot reads.
**The historical simulation lab.** Replays past market data through your strategy with a conservative fill model, producing reports with profit/loss, drawdown, win rate, and a per-trade ledger. Deliberately separate from the live runtime so you can simulate without affecting trading.
**The notification channel.** Posts trade-close notifications, system alerts, and daily summaries to your Telegram chat. Notification-only by design — there are no chat commands. All operator control happens in the Dashboard.
**Your authenticated control surface.** A web cockpit that shows live positions, performance, system health, and lets you flip the kill switch, switch modes, allocate capital, or close positions manually.
## A typical day, end to end
**Reading the diagram from the top down:**
1. You author a **strategy** in the **SignalEditor**.
2. Once you click Start, the SignalEditor's scheduler evaluates your strategy on your chosen timeframe (e.g., every `15m` bar close).
3. When your trigger fires, the SignalEditor emits a **webhook signal** to the **SignalsBot**.
4. The SignalsBot validates the signal (shared secret) and writes a configuration update.
5. The **TradingBot** reads the updated configuration and places real orders on your exchange.
6. As trades close, the result is written back to the configuration and visible to:
* The **Dashboard** (you check via browser)
* The **TelegramBot** (which pings you)
7. You stay in the loop. The bot does the work.
## What runs where
The four core services that your CapRover-style deploy brings up:
* **TradingBot** — the execution engine talking to your exchange.
* **TelegramBot** — the notification channel.
* **Dashboard** — the operator's web cockpit.
* **PostgreSQL** — the local data store.
These run continuously, restart automatically on failure, and produce all your trading data locally on your machine. Nothing leaves your VPS except outbound calls to your exchange and to Telegram's notification API.
* **SignalEditor** — runs alongside the core stack when you want to author strategies visually. Once your strategy is saved and configured via the dashboard, the SignalEditor doesn't need to run continuously.
* **SignalsBot** — runs when you want to receive webhook signals (from the SignalEditor's scheduler or from external producers like TradingView). If you only use the bot's pre-built modes, you may not need it.
* **Backtester** — runs on demand when you want to simulate a strategy. Most operators use a hosted Backtester (we run one for you) rather than self-hosting it, since backtests are heavy compute.
* **License verification** — a small centralized service that validates your unCoded license. It does not see your trading data.
* **Hosted Backtester** (optional) — for operators who don't want to self-host the simulation engine. Runs as a paid feature for license holders.
These are vendor services, not part of your trading stack. If they ever become unreachable, your live trading continues uninterrupted via the orders already on your exchange.
## The contracts between modules
Each module talks to its neighbors through **clean, stable contracts**. You don't need to know the implementation details, but you should know the contracts because they define what's possible and what's safe.
| Contract | What flows | Used by |
| ----------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Strategy definition** | Your visually-authored strategies (indicators + conditions + triggers + risk rules) saved as files | SignalEditor publishes; SignalsBot/TradingBot/Backtester consume |
| **Signal payload** | A single trade signal: exchange, symbol, side, intent, confidence, timestamp | SignalEditor's scheduler emits; SignalsBot receives; TradingBot acts |
| **Configuration state** | Your active mode, capital allocation, kill switch, per-pair settings | Dashboard writes; TradingBot polls; TelegramBot reads |
| **Trade record** | Every closed round-trip with realized P\&L, fees, slippage | TradingBot writes; Dashboard displays; TelegramBot notifies |
Because these contracts are explicit and stable, you can:
* **Replace any module** with a different implementation that respects the contract.
* **Add new sources** (e.g., your own Python signal generator) without touching the core engine.
* **Audit any trade** back to the signal that produced it, and any signal back to the bar conditions that fired it.
## Why this design matters for you
If one module crashes, the others keep working. If your TelegramBot loses connectivity, your trades continue executing — you just don't get pings. If your Dashboard is down, the TradingBot keeps trading — you just can't see the panels until it's back. This is the operational benefit of separation of concerns.
Every signal, every trade, every operator action is logged. You can answer questions like "why did the bot trade XYZ at 14:32 on Monday?" by reading the trade record, then the signal record that caused it, then the bar values that fired the signal. No magic, no hidden state.
When unCoded ships an update, you upgrade one module at a time. The others continue running. There is no "forced full-stack redeploy" — you choose what to upgrade, when.
Want a second exchange? Run a second TradingBot container with a different `EXCHANGE_ID`. Want multiple strategies isolated? Use sub-accounts. Want a more powerful Backtester? Move it to a beefier host. Each module scales independently because each owns one job.
## What this means in practice
**The mental model that will save you the most time:**
* **The SignalEditor produces signals.** Period. It's where authoring and live evaluation both happen.
* **The SignalsBot receives signals.** It is a webhook receiver, not a strategy evaluator. Don't confuse the two.
* **The TradingBot acts on configuration.** It does not "consume signals" directly — signals become configuration writes that the TradingBot then reads.
* **The Dashboard is your only authenticated control surface.** Telegram is read-only. Always.
## What's next
A more visual look at how the modules deploy on your VPS and how data flows through the stack.
Every term we use in this documentation, defined in plain language.
Detailed pages on each of the 6 modules.
The fastest path from this conceptual model to running trades.