# Architecture Overview PaperMarket is a server hosted web application that sits between a trader and live Polymarket markets.\ End users only ever see a browser based interface. All logic that touches Polymarket APIs, runs simulations or updates account state executes on the server under the control of the PaperMarket team. At a high level the system is split into three layers * **Web client** – renders the UI in the browser, displays markets, books, charts and portfolio, and forwards user actions to the backend over HTTPS. * **Application server** – exposes a set of HTTP endpoints that implement the simulation logic, talk to Polymarket’s public APIs and mediate all reads and writes to the database. * **Off chain datastore** – a relational database that stores users, virtual balances, simulated orders, trades, positions and lightweight metadata about Polymarket markets. The design is deliberately centralized. Traders never run their own instances. They connect to a single hosted deployment that owns the code, the configuration and the data. ### Component responsibilities #### Web client The web client is a standard browser application. Its responsibilities are intentionally narrow * render the current state of the simulation account (cash, positions, orders, trades) * render the current view of the selected Polymarket market (question, order book, chart) * collect structured input from the user (which market to load, which order to simulate) * send this input to the application server as JSON over HTTPS and display the server’s response The client does not implement any matching or pricing logic.\ It treats the server as the only source of truth for account state and treats Polymarket as a read only market data source behind that server. #### Application server The application server is the core of PaperMarket. It owns three main responsibilities * **Polymarket integration** – read only access to Polymarket public endpoints for * resolving links and slugs into concrete markets and token ids * fetching live order books for YES and NO tokens * fetching historical prices for charting * **Simulation engine** – deterministic matching of virtual orders against the latest Polymarket order book under simple risk rules * enforce that buys are limited by virtual cash * enforce that sells are limited by existing long positions * forbid shorting and leverage * **State management** – persist all simulation state off chain * user identities and authentication data * per user cash balances * order and trade logs * net positions per token and derived statistics (average entry, realized impact, etc.) The server is stateless between requests except for its connection to the datastore. Every change to the simulation account is driven by an explicit HTTP request from the web client and results in explicit writes to the database. #### Off chain datastore The datastore is a relational schema optimized around a small set of core entities * users and their virtual cash balances * markets the user has interacted with (identified by Polymarket ids and slugs) * orders submitted in the simulation environment * trades generated by matching those orders against the Polymarket book * positions aggregated per user and per Polymarket token Only the application server talks to the database.\ The web client never sees database credentials and never accesses storage directly. ### Interaction with Polymarket PaperMarket treats Polymarket as its market data provider, not as an execution venue. The server side integration follows a simple pattern 1. **Market resolution**\ When a user pastes a Polymarket URL or slug, the server calls Polymarket APIs to resolve it into a specific event and market and to identify the relevant YES and NO tokens. 2. **Market data**\ For a resolved market the server pulls * live CLOB snapshots for each token to obtain depth and best prices * historical price series for charting and context 3. **No write access**\ The server never submits orders, never signs transactions and never moves USDC. All calls to Polymarket are read only and use public endpoints. As a result, PaperMarket can replay “what would have happened” if a trader had sent an order into the live Polymarket book at a given moment without actually touching any on chain state. ### Simulation flow at a glance From the outside PaperMarket behaves like a lightweight trading terminal. Internally it runs a simple but explicit simulation loop. A typical sequence looks like this 1. **Load market**\ The client sends a Polymarket link or slug to the server. The server resolves it, stores or updates minimal metadata about the market and returns a normalized description (question text, ids, token references). 2. **Fetch live view**\ The client asks for order book and history. The server calls Polymarket, builds a clean snapshot of the book and a time series for the chart and returns them to be rendered. 3. **Simulate order**\ When the user submits a virtual order intent (side, size, type, optional limit), the client forwards it to the server. The server: * loads the latest account state for that user from the datastore * pulls a fresh CLOB snapshot for the relevant token * applies the matching logic against that snapshot under the user’s balance and position constraints * records one order and one or more trades in the datastore * updates cash and positions accordingly 4. **Refresh account view**\ The client requests the updated account snapshot. The server returns the new balance, updated positions and trade log. The portfolio uses these together with current mid prices from Polymarket to display value and PnL. All of these steps are internal to the hosted instance of PaperMarket. End users see a pure web front end and never interact directly with Polymarket APIs or with the database. ### Access and control PaperMarket is designed as a centrally hosted system * only the project team controls the server, the datastore and the configuration * traders interact with the system strictly through the public web interface * no source code, schema or deployment details are exposed through the documentation From a reviewer’s perspective this architecture ensures that * all simulation state is kept off chain under one controlled environment * all usage of Polymarket is read only and clearly scoped * the behaviour that traders see in the browser is fully determined by the backend logic, not by arbitrary client side code --- # 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: ``` GET https://papermarket.gitbook.io/papermarket/technical/architecture-overview.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.