# venkatarohan/stock_exchange architecture

> Architecture diagram of the GitHub repository venkatarohan/stock_exchange, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/venkatarohan/stock_exchange
- Repository: https://github.com/venkatarohan/stock_exchange

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices trading platform.
- Components:
- Frontend (React/Vite/Tailwind) for user UI (login, signup, order placement, order book, account).
- API service (Node.js/Express/TypeScript) exposing REST endpoints (login, signup, ticker, orders, trades, etc.).
- WebSockets service (Node.js/TypeScript) for real-time pushes (order book updates, trades, account changes).
- Engine service (Node.js/TypeScript) implementing the matching engine and snapshot routines.
- Database service (Postgres/Timescale via Prisma ORM) for persisting users, orders, trades, balances; uses hypertables for time-series.
- Message bus (RabbitMQ) facilitating event-driven communication between API, DB, Engine, and WS.
- NGINX as ingress/reverse-proxy in front of API, WS, and static frontend assets.

##### File Structure Highlights
- Top-level services:
/frontend — UI code, compiled via Vite.
/api — REST service, Dockerfile, routes under src/routes.
/websockets — WS service, SubscriptionManager, UserManager.
/engine — matching engine, trades folder, orderbook util.
/db — Prisma migrations, seed, DB initialization.
- Shared patterns: RabbitMqManager.ts in api, engine, and db for AMQP connectivity.
- Configuration: docker-compose.yml orchestrates all containers; nginx.conf configures reverse proxy.

##### Key Architectural Patterns
- Microservices with dedicated bounded contexts: API vs. Engine vs. DB vs. WS.
- Event-driven messaging via RabbitMQ for decoupling and scalability.
- CQRS-like separation: API writes/reads, Engine publishes fills/trades, WS pushes to clients.
- TimescaleDB hypertables for efficient time-series trade data.
- Containerization with Docker and service orchestration via Docker Compose.

- Browser / Mobile Client (React App)
- NGINX Reverse Proxy
- API Service
- WebSockets Service
- Engine Service
- Database Service (Postgres/Timescale via Prisma)
- RabbitMQ Broker
- Optional: Admin/CLI (seed, DB migrations)

1. Client → NGINX: HTTP GET/POST for static assets and API calls
2. NGINX → Frontend Container (served static)
3. Client ↔ NGINX → WebSockets endpoint for real-time updates
4. API → RabbitMQ: publish commands (new order, cancel)
5. Engine ← RabbitMQ: consumes order commands, matches, publishes trade events
6. DB Service ← RabbitMQ: consumes events to persist trades, update balances
7. WebSockets ← RabbitMQ: consumes events to push to connected clients
8. API → DB (Prisma) for CRUD on users, account info, historical queries

- Frontend: React, TypeScript, Vite, Tailwind CSS
- API: Node.js, Express, TypeScript, Prisma ORM
- WebSockets: Node.js, ws or socket.io, TypeScript
- Engine: Node.js, TypeScript, custom matching logic
- DB: Postgres with TimescaleDB extension, Prisma migrations
- Message Bus: RabbitMQ
- Orchestration: Docker Compose, Dockerfiles per service
- Reverse Proxy: NGINX

d. Architectural Principles
- Clear separation of concerns (UI vs. business logic vs. data storage vs. real-time push).
- Loose coupling via message queue.
- Single responsibility per service (e.g., Engine does only matching).
- Scalability: each service can be scaled horizontally behind NGINX or via additional RabbitMQ consumers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Network"
        direction TB
        Clients["Browser/Mobile Client"]:::external
        AdminCLI["Admin CLI"]:::external

        NGINX["NGINX Reverse Proxy\n(nginx.conf)"]:::proxy
        Frontend["Frontend\nReact/TS/Vite/Tailwind"]:::frontend
        API["API Service\nNode.js/Express/TS"]:::api
        WS["WebSockets Service\nNode.js/TS"]:::websockets
        Engine["Engine Service\nNode.js/TS"]:::engine
        MQ["RabbitMQ Broker"]:::mq
        DB["Postgres/TimescaleDB\nPrisma ORM"]:::db
    end

    Clients -->|"HTTP/REST & Static"| NGINX
    Clients -->|"WebSocket"| NGINX

    NGINX -->|"Serves Static Assets"| Frontend
    NGINX -->|"Proxies HTTP"| API
    NGINX -->|"Proxies WS"| WS

    API -->|"SQL (Prisma)"| DB
    API -->|"AMQP Commands"| MQ

    MQ -->|"Consume Orders"| Engine
    Engine -->|"Publish Trade Events"| MQ

    MQ -->|"Persist Events"| DB
    MQ -->|"Push Updates"| WS

    classDef external fill:#cccccc,stroke:#000,stroke-width:1px;
    classDef proxy fill:#999999,stroke:#000,stroke-width:1px;
    classDef frontend fill:#007BFF,stroke:#000,stroke-width:1px,color:#fff;
    classDef api fill:#28a745,stroke:#000,stroke-width:1px,color:#fff;
    classDef websockets fill:#20c997,stroke:#000,stroke-width:1px,color:#fff;
    classDef engine fill:#fd7e14,stroke:#000,stroke-width:1px,color:#fff;
    classDef mq fill:#ffc107,stroke:#000,stroke-width:1px;
    classDef db fill:#6f42c1,stroke:#000,stroke-width:1px,color:#fff;

    click Frontend "https://github.com/venkatarohan/stock_exchange/tree/main//frontend"
    click API "https://github.com/venkatarohan/stock_exchange/blob/main//api/src/index.ts"
    click WS "https://github.com/venkatarohan/stock_exchange/blob/main//websockets/src/index.ts"
    click Engine "https://github.com/venkatarohan/stock_exchange/blob/main//engine/src/index.ts"
    click DB "https://github.com/venkatarohan/stock_exchange/blob/main//db/src/index.ts"
    click NGINX "https://github.com/venkatarohan/stock_exchange/blob/main/nginx.conf"
```
