> ## 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.

# Architecture — How unCoded Runs on Your Server

> A user-facing view of how the unCoded stack deploys, where data lives, and what to expect operationally.

<Info>
  **This page covers what runs on your server, what data lives where, and what your operational footprint looks like.** It is a user-facing architectural overview — not a developer reference. If you are evaluating unCoded for your operation or your investment, this page should answer "what am I actually deploying?"
</Info>

## The deployment model in one sentence

**unCoded runs as a small set of Docker containers on your own VPS, with all your trading data stored locally on that VPS, and the only outbound network calls being to your exchange and to Telegram.**

That's it. There is no shared cloud. There is no centralized data lake holding your positions. There is no proprietary backend that needs to stay reachable for your bot to keep trading.

## What your VPS actually runs

<CardGroup cols={2}>
  <Card title="A handful of Docker containers" icon="docker">
    The four core services (TradingBot, TelegramBot, Dashboard, Database) are bundled as a CapRover-style One-Click app. You bring up the entire stack with one command.
  </Card>

  <Card title="Optional add-on services" icon="puzzle-piece">
    SignalEditor and SignalsBot are optional containers you start when you want webhook-driven authoring. They sit alongside the core four.
  </Card>

  <Card title="A persistent data volume" icon="database">
    Your local database (PostgreSQL) holds every active trade-pair configuration, every executed trade, every operator action. Backed up on a schedule of your choice.
  </Card>

  <Card title="Read-only mounts to logs" icon="folder-open">
    The Dashboard reads (read-only) the TradingBot's container logs to stream them to your browser when you open the "Logs" panel.
  </Card>
</CardGroup>

## Hardware footprint

| Resource             | Minimum (single exchange, no heavy backtests) | **Recommended (full stack, multi-exchange)** | Heavy operations (multi-host operator)       |
| -------------------- | --------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
| **vCPU**             | 2                                             | **4**                                        | 8                                            |
| **RAM**              | 4 GB                                          | **8 GB**                                     | 16 GB                                        |
| **Disk**             | 40 GB SSD                                     | **80 GB NVMe SSD**                           | 200 GB NVMe SSD                              |
| **Network**          | Stable outbound                               | Stable outbound, low jitter                  | Same, plus geographic proximity to exchanges |
| **Monthly VPS cost** | `€5–€10`                                      | **`€10–€15`**                                | `€30+`                                       |

<Tip>
  **Recommendation for 95% of operators**: the **`4 vCPU / 8 GB / 80 GB NVMe SSD`** profile. This runs the full CapRover bundle plus optional SignalEditor/SignalsBot for **`€10–€15/month`** at hosts like Netcup or Hetzner. It comfortably supports multiple exchanges and reasonable backtest workloads.
</Tip>

## What gets deployed

When you spin up unCoded via the One-Click installer, you get **four core services** plus an optional database visualization layer:

<AccordionGroup>
  <Accordion title="PostgreSQL — your local database" icon="database">
    A single PostgreSQL container that stores:

    * **Active trade pair configuration** (which symbols you're trading, under which mode)
    * **Per-mode settings** (the buy ladder, sell ladder, trailing-stop policy for each of the 9 modes)
    * **Closed trade history** (every round-trip your bot has executed)
    * **System status** (heartbeats, connection state, current configuration hash)
    * **UI preferences** (your dashboard layout, theme, etc.)

    Everything that needs to survive a restart lives here. Back this up.
  </Accordion>

  <Accordion title="TradingBot — the execution engine" icon="robot">
    The container that talks to your exchange. It:

    * Polls the database for the current trade-pair configuration
    * Subscribes to your exchange's market data and account updates
    * Places, monitors, and manages orders
    * Writes closed trades back to the database

    This is the only container that holds your exchange API credentials.
  </Accordion>

  <Accordion title="TelegramBot — the notification channel" icon="paper-plane">
    The container that posts trade-close notifications to your Telegram chat. It:

    * Polls the database for newly-closed trades
    * Formats them into clean text messages
    * Sends them via Telegram's bot API
    * Handles rate limits gracefully

    This is the only container that holds your Telegram bot token.
  </Accordion>

  <Accordion title="Dashboard — your operator's web cockpit" icon="gauge">
    The container that serves your authenticated browser interface. It:

    * Reads from the database for live panels (positions, performance, system stats)
    * Streams TradingBot logs to your browser via the Logs panel
    * Lets you flip the kill switch, switch modes, allocate capital
    * Optionally serves a Google Account-linking onboarding step

    This is the only container exposed to the internet (behind your reverse proxy with TLS).
  </Accordion>
</AccordionGroup>

## What you can add as you grow

<AccordionGroup>
  <Accordion title="SignalEditor (optional)" icon="wand-magic-sparkles">
    Spin up the SignalEditor container when you want to author strategies visually. It serves a web canvas for composing indicators, conditions, and triggers. Once your strategy is published and the SignalEditor's scheduler is running it, you can leave the editor running or stop it (the strategy keeps running as long as the scheduler container is alive).

    Resource cost: an additional `300–500 MB` RAM, sub-percent CPU at idle.
  </Accordion>

  <Accordion title="SignalsBot (optional)" icon="satellite-dish">
    Spin up the SignalsBot container when you want to receive webhook signals — either from the SignalEditor's running strategies, or from external sources like TradingView. The SignalsBot validates incoming webhooks (shared secret) and writes the resulting configuration updates to PostgreSQL.

    Resource cost: `100–200 MB` RAM, sub-percent CPU at idle, 64 KB body cap on incoming webhooks.
  </Accordion>

  <Accordion title="A second TradingBot for a second exchange" icon="server">
    Each TradingBot container is **single-exchange** by design. To run on multiple exchanges (e.g., Binance and Bybit simultaneously), you spin up a second TradingBot container with `EXCHANGE_ID=bybit` (or whichever venue), pointing at the same shared database. Both bots independently manage their respective exchange.

    Each additional bot adds about `100–200 MB` RAM.
  </Accordion>

  <Accordion title="A self-hosted Backtester (optional)" icon="flask">
    Most operators use the vendor-hosted Backtester (it's heavier compute and benefits from being centralized). If you prefer self-hosted, you can run it as a separate container.

    Resource cost: `500 MB – 2 GB` RAM per active backtest. With concurrency cap of 2, plan for `1–4 GB` peak RAM if you self-host. Most operators don't bother.
  </Accordion>
</AccordionGroup>

## Network footprint

<CardGroup cols={2}>
  <Card title="Outbound calls" icon="arrow-up-right-from-square">
    * To your exchange's REST + WebSocket endpoints (continuous)
    * To Telegram's bot API (when notifications fire)
    * To the unCoded license-verification service (occasional heartbeats)
    * To your authentication provider (when you log into the dashboard)

    No proprietary cloud, no centralized data lake.
  </Card>

  <Card title="Inbound exposure" icon="arrow-down-to-line">
    * **Dashboard's HTTP port** (behind your TLS reverse proxy) for browser access
    * **SignalsBot's webhook port** (only if you use external webhook sources like TradingView)

    Everything else is private to the VPS's internal Docker network.
  </Card>
</CardGroup>

<Warning>
  **Always put a TLS reverse proxy in front of your dashboard.** Caddy and nginx-proxy-manager are operator favorites. Never expose the dashboard's raw HTTP port to the public internet — TLS protects your dashboard password from interception.
</Warning>

## Where your data lives

| Data                                                  | Location                                 | Backed up?                                          | Survives full VPS loss?                                         |
| ----------------------------------------------------- | ---------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------- |
| **Closed trade history**                              | Local PostgreSQL on your VPS             | If you set up backups, yes                          | Only if backups are off-site                                    |
| **Active configuration** (mode, capital, kill switch) | Local PostgreSQL                         | Same                                                | Same                                                            |
| **Strategy definitions**                              | Local disk in the SignalEditor container | If you back up the volume, yes                      | Only if backups are off-site                                    |
| **Exchange API keys**                                 | Encrypted environment file on your VPS   | Should be backed up to a secure location separately | No — never sync your keys to a public backup                    |
| **Open positions**                                    | On the exchange itself                   | The exchange holds them; not local                  | Yes — your positions on the exchange are unaffected by VPS loss |
| **License entitlement**                               | Vendor service (centralized)             | Centralized backup                                  | Yes — your license is rooted in your account, not your server   |

<Tip>
  **Recommended backup strategy**:

  * Daily database snapshot to off-site storage (any cloud provider works)
  * Weekly full VPS image
  * API keys: stored in a password manager, never in a Git repo or shared backup
  * Strategies: synced to a private Git repo or cloud drive

  This means: if your VPS dies tomorrow, you can spin up a new VPS, restore the database, re-deploy the stack, and resume trading within an hour. Your funds on the exchange were never at risk.
</Tip>

## What happens during a restart

<AccordionGroup>
  <Accordion title="Planned restart (you stop and restart the stack)" icon="rotate">
    1. The TradingBot stops sending new orders.
    2. **Open positions on the exchange continue to be honored** — sell-ladder rungs already placed will fill as price moves.
    3. The TelegramBot stops sending notifications during downtime; queues anything from after the database came back.
    4. On restart, the TradingBot reconciles its view against the exchange — it observes any fills that happened during downtime and updates its records.
    5. Trading resumes within seconds.
  </Accordion>

  <Accordion title="Unplanned crash (your VPS reboots)" icon="bolt">
    1. Same as above — Docker's restart policy brings the containers back automatically.
    2. The reconciliation step ensures no fills are lost.
    3. **Important caveat**: while the bot is offline, the trailing stop is not actively re-priced as new highs are made. If your trailing-stop reference would have moved during downtime, on restart the stop is at its last placed level, not at the highest price during the gap.
  </Accordion>

  <Accordion title="Total VPS loss (provider failure, accidental delete)" icon="explosion">
    1. Your funds on the exchange are **completely safe** — they were never on your VPS.
    2. Open positions continue to honor their already-placed sell ladders and trailing stops on the exchange side.
    3. You spin up a new VPS, restore your database backup, re-deploy the stack, and resume trading.
    4. The only data you lose is the local audit trail since your last backup.

    This is why **daily backups** are the single most important operational habit.
  </Accordion>
</AccordionGroup>

## What unCoded never does

<Warning>
  **Architectural commitments that protect you:**

  * ❌ Never holds your exchange API keys on a centralized service.
  * ❌ Never has access to your funds (your API keys should always have withdrawal disabled).
  * ❌ Never streams your trading data to a centralized cloud.
  * ❌ Never auto-updates without your explicit approval.
  * ❌ Never executes a trade you didn't authorize via your strategy or configuration.
  * ❌ Never accepts remote commands from your Telegram chat (notification-only by design).
</Warning>

## What's next

<CardGroup cols={2}>
  <Card title="Modules Overview" icon="layer-group" href="/concepts/overview">
    The six modules and their conceptual roles.
  </Card>

  <Card title="Glossary" icon="book" href="/concepts/glossary">
    Every term defined.
  </Card>

  <Card title="Quickstart" icon="forward" href="/quickstart">
    From this architectural understanding to your first running trade.
  </Card>

  <Card title="Security Philosophy" icon="shield" href="/about/security-philosophy">
    Why we made the architectural choices we did, and how they protect you.
  </Card>
</CardGroup>