bhupeshv29/perps-v2

1. This is a Bun-based Turborepo for a trading/exchange system, not a single app. The repo is split into multiple deployable services plus shared packages, with turbo used to coordinate builds/dev across the monorepo.

2. The frontend lives in apps/frontend and is a Next.js app. It contains the user-facing trading UI: dashboard, markets, orders, positions, admin screens, sign-in/sign-up, and several domain-specific components such as charts, order entry, order books, fills, and balance/deposit/on-ramp views.

3. The frontend does not talk directly to every backend service. It has an API proxy layer under app/api/backend/[...path], an auth route under app/api/auth/[...nextauth], and dedicated client-side state stores for market, account, and websocket state. That makes the browser-facing app a presentation and session layer over the internal backend services.

4. apps/backend is the main HTTP API boundary. Its middleware set shows the core responsibilities: authentication, admin authorization, logging, rate limiting, request validation, and error handling. This service likely exposes the user/account/order/admin APIs consumed by the frontend proxy.

5. apps/engine is the trading core and is the most important backend subsystem. Its source files indicate clear internal domains: order handling, orderbook management, balances, positions, risk checks, liquidations, market-price consumption, replay, hydration, state management, and snapshot/recovery. Architecturally, this is the stateful matching/risk engine that maintains authoritative market and account state.

6. The engine is designed around persistence and recovery rather than being purely in-memory. The snapshot folder and replay/hydrate modules indicate it can rebuild state from stored events or snapshots, which is important for crash recovery, restarts, and deterministic reprocessing.

7. Redis is the main intra-system messaging backbone. There is a shared packages/redis library with client/producer/consumer/stream abstractions, and each service that participates in async processing has its own Redis integration. This suggests Redis Streams or similar queue semantics are used to connect the API, engine, workers, and websocket fanout.

8. Real-time market data and user updates are separated from the HTTP API. apps/ws-gateway is a dedicated websocket service, and the frontend has a ws-provider plus a ws-store, implying the browser subscribes to live feeds through this gateway rather than polling REST endpoints.

9. Background processing is split into workers. apps/price-worker likely ingests external market prices into the system, while apps/db-worker appears to consume event streams and apply durable writes or projections into the database. This keeps the core engine and API responsive while persistence and market-data ingestion happen asynchronously.

10. packages/db is the database boundary, built with Prisma and backed by migrations and seed data. Its schema evolves around the trading domain: markets, orders, positions, closed positions, on-ramp, realized PnL, and timestamps. That makes the database a system-of-record for durable business entities and reporting, not the engine’s primary execution store.

11. Shared code is centralized in packages/common, which holds constants and types used across services. This reduces schema drift between the frontend, API, engine, and workers, especially for domain objects like markets, orders, and account-related payloads.

12. Infrastructure-wise, the repo is structured for multiple long-running services plus a database and Redis, with Docker Compose present at the root. The practical runtime boundary is: browser → Next.js frontend → backend API → engine/Redis/db worker, with websocket updates flowing separately through the gateway and persistent state flowing into Postgres via Prisma-backed writes.