> For the complete documentation index, see [llms.txt](https://docs.pretoke.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pretoke.xyz/how-it-works/system-overview.md). # System Overview This page gives a bird's-eye view of how the platform is built, for readers who want to understand what happens behind the scenes. ## The big picture ``` ┌────────────────────┐ │ Your Browser / │ │ Telegram Mini App │ └──────────┬──────────┘ │ HTTPS (REST) + WebSocket ▼ ┌────────────────────┐ │ API Gateway │ ← the ONLY public entry point │ (auth check, cache, │ │ rate limits, routing)│ └──────────┬──────────┘ ┌───────────┬──────────┼───────────┬────────────┐ ▼ ▼ ▼ ▼ ▼ ┌──────────┐┌──────────┐┌───────────┐┌───────────┐┌───────────────┐ │ Auth ││ Market ││ Trading ││ Settlement││ User / │ │ Service ││ Service ││ Service ││ Service ││ Notification │ └──────────┘└──────────┘└───────────┘└─────┬─────┘└───────────────┘ │ ▼ ┌──────────────────┐ │ TON Blockchain │ │ (smart contracts) │ └──────────────────┘ ``` Everything you interact with goes through a single **API Gateway**. Behind it, a set of independent services each handle one job: | Service | Responsibility | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **API Gateway** | The public front door. Verifies your login token, applies rate limits, caches frequently-read data, and forwards requests to the right internal service. Also runs the WebSocket server for live updates. | | **Auth Service** | Verifies your wallet's TON Connect signature and issues session tokens. | | **Market Service** | Owns the catalog of events and markets — titles, categories, status, and lifecycle (open → closed → resolved). | | **Trading Service** | Runs the order book and the automated market maker; matches trades and computes prices. | | **Settlement Service** | Talks to the TON blockchain — deposits, withdrawals, and converting trades into real on-chain outcome-token positions. | | **User Service** | Tracks your balance, positions, trade history, and price charts. | | **Autofill Service** | A background job that imports real-world events and markets (currently sourced from Polymarket's public event catalog) so there's always something to trade. | | **Notification Service** | Sends you in-app and Telegram notifications about fills, settlements, and resolutions. | None of the internal services are reachable directly from the internet — only the API Gateway is public. This is an intentional security boundary: the gateway is where every request is authenticated before it's allowed to reach anything else. ## What happens when you trade — end to end 1. You place an order or market trade in the app. 2. The **API Gateway** checks your session token, applies rate limiting, and forwards the request to the **Trading Service**. 3. The Trading Service matches your order against the order book and/or the automated market maker, and returns a fill. 4. The fill is broadcast over Kafka (an internal event stream) to the **Settlement Service**, which queues the on-chain operation (splitting collateral into outcome tokens, or merging them back). 5. The Settlement Service submits the actual transaction to the **TON blockchain**, using the platform's smart contracts (`ConditionRegistry` and `LmsrMarketMaker` — see [Smart Contracts](/smart-contracts/architecture-overview.md)). 6. Once confirmed on-chain, a confirmation event flows back, updating your trade's settlement status and triggering a notification. Your balance and positions update immediately in step 3-4 (off-chain, for a responsive experience) — the on-chain settlement in steps 5-6 catches up shortly after, so your holdings are always backed by a real blockchain position. Continue to [Wallet Login Explained](/how-it-works/wallet-login-explained.md) for how step 2's authentication actually works, or [How Trades Settle On-Chain](/how-it-works/settlement-explained.md) for more on steps 4-6. --- # 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.pretoke.xyz/how-it-works/system-overview.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.