bhupeshv29/perps-exchange-platform

1. This is a monorepo for a simplified perpetual futures exchange. The system is split into independently deployed services: a Next.js frontend, an HTTP backend API, a matching engine, a DB worker, a WebSocket gateway, and a price worker. Shared packages provide common market math, Redis helpers, database access, UI components, and config.

2. The frontend lives in apps/frontend and is the user-facing trading app. It uses Next.js app routes, NextAuth-style auth plumbing, TanStack/React Query-style data fetching, local state stores, and a WebSocket layer for realtime market/account updates. The trade page is composed from specialized panels for order entry, depth, fills, positions, balances, and history.

3. The backend in apps/backend is the request gateway for authenticated REST actions such as account, auth, market, and order operations. Its key role is orchestration: validate input, authenticate the user, publish a request into Redis, wait for the engine response, and return the HTTP result. It does not own balances, positions, orders, or orderbook state.

4. The matching engine in apps/engine is the source of truth for trading state. It keeps balances, orders, orderbooks, positions, and mark prices in memory, performs order matching with price-time priority, computes fills and PnL, handles liquidation, and generates depth updates. It also persists periodic snapshots to disk for recovery after restart.

5. The engine receives inputs from two Redis-backed channels: trading requests and price updates. Requests come from the backend through Redis Streams; mark price updates come from the price worker through another stream. After applying state transitions, the engine emits two kinds of outputs: durable events for database persistence and realtime events for user/client updates.

6. Persistence is isolated in apps/dbWorker. That service consumes engine-generated database events from Redis Streams and writes them to PostgreSQL via Prisma. The schema layer in packages/db defines the relational history the platform keeps, such as users, balances, orders, fills, and closed positions. Notably, open positions are not stored in Postgres; they exist only in the engine’s runtime state.

7. Realtime fanout is handled by apps/wsGateway. It subscribes to Redis Pub/Sub events produced by the engine and broadcasts them over WebSocket to connected clients. The gateway also authenticates socket connections using a JWT cookie and attaches a user identity so it can distinguish private events from market-wide events.

8. The price worker in apps/priceWorker is the external market-data ingress for mark-price updates. Its output is fed into Redis Streams and consumed by the engine for liquidation and unrealized PnL calculations. This worker is part of the risk loop because it drives the engine’s view of current market value.

9. Redis is the core integration backbone. Streams are used for ordered, reliable processing between services: engine requests, engine responses, DB events, and price updates. Pub/Sub is used only for low-latency websocket fanout. The architecture intentionally separates these two patterns so critical state changes are durable while UI updates stay fast.

10. The shared packages define the common contract surface. packages/common contains market utilities, constants, formatting, and stream/type helpers; packages/redis centralizes Redis client and stream/pubsub primitives; packages/ui provides reusable frontend components; packages/eslint-config and packages/typescript-config standardize tooling across apps.

11. The main business flow is: frontend submits an order or account action to the backend, backend writes a request to Redis, engine consumes it and mutates trading state, engine emits persistence and websocket events, DB worker writes history to Postgres, and WebSocket gateway pushes live updates back to subscribed clients. This is the central architecture boundary: the engine owns live state, while the other services are thin adapters around it.

12. Startup recovery is a first-class concern. The engine periodically snapshots its in-memory state to a local file and reloads that snapshot on restart before resuming stream consumption. That means the system can recover trading state without reconstructing open orders or positions solely from the database.

13. Deployment is containerized per service. Each app has its own production Dockerfile, with a root docker-compose setup for local or production-style orchestration. The repo also includes docs for installation and e2e testing, which suggests the system is intended to be run as a multi-process distributed exchange rather than a single web server.