# adithyasai3/marketplay architecture

> Architecture diagram of the GitHub repository adithyasai3/marketplay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adithyasai3/marketplay
- Repository: https://github.com/adithyasai3/marketplay

## Overview

MarketPlay is a full-stack paper-trading simulator: users register or sign in, explore simulated NSE stock prices, buy and sell with virtual cash, then review holdings, performance, and trade history. The React SPA calls a Spring Boot REST API and receives live price updates over WebSocket. The backend separates controllers, domain services, and repositories, with PostgreSQL-backed account and trading state and Redis-backed leaderboard caching. The README documents these product capabilities; sampled source confirms authentication, trade execution, portfolio calculations, stock operations, and frontend API behavior, but not every feature’s internal wiring.

Main entry points: [`backend/src/main/java/com/marketplay/controller`](https://github.com/adithyasai3/marketplay/tree/main/backend/src/main/java/com/marketplay/controller) (REST controllers), [`backend/src/main/java/com/marketplay/repository`](https://github.com/adithyasai3/marketplay/tree/main/backend/src/main/java/com/marketplay/repository) (Data repositories), [`frontend/src/pages`](https://github.com/adithyasai3/marketplay/tree/main/frontend/src/pages) (Feature pages), [`backend/src/main/java/com/marketplay/service/AuthService.java`](https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/AuthService.java) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React application"]
  node_pages["Feature pages"]
  node_app["Route access<br/>[App.tsx]"]
  node_authcontext["Auth context<br/>[AuthContext.tsx]"]
  node_apiclient["API client<br/>[client.ts]"]
  node_featureapis["Resource APIs"]
  node_pricehook["Live price hook<br/>[useStockPrices.ts]"]
end

subgraph group_api["API and domain"]
  node_rest["REST controllers"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_jwt["JWT security<br/>[JwtService.java]"]
  node_stockservice["Stock catalog<br/>[StockService.java]"]
  node_trade["Trade execution<br/>[TradeService.java]"]
  node_portfolio["Portfolio analytics"]
  node_otherfeatures["Other services"]
end

subgraph group_market["Market updates"]
  node_simulator["Price simulator"]
  node_websocket["WebSocket updates"]
end

subgraph group_state["Persistent state"]
  node_repositories["Data repositories"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis cache")]
end

node_user(("Investor or admin"))
node_browser(("Browser client"))

node_user -->|"uses"| node_app
node_app -->|"routes"| node_pages
node_pages -->|"uses auth"| node_authcontext
node_pages -->|"requests data"| node_featureapis
node_authcontext -->|"auth requests"| node_featureapis
node_featureapis -->|"uses"| node_apiclient
node_apiclient -->|"HTTP requests"| node_rest
node_rest -->|"delegates auth"| node_auth
node_auth -->|"creates tokens"| node_jwt
node_rest -->|"stock operations"| node_stockservice
node_rest -->|"buy, sell, history"| node_trade
node_rest -->|"portfolio requests"| node_portfolio
node_rest -->|"feature requests"| node_otherfeatures
node_trade -->|"looks up stock"| node_stockservice
node_trade -->|"reads and writes"| node_repositories
node_portfolio -->|"reads holdings"| node_repositories
node_auth -->|"reads and writes"| node_repositories
node_stockservice -->|"reads and writes"| node_repositories
node_otherfeatures -->|"feature state"| node_repositories
node_repositories -->|"persists state"| node_postgres
node_otherfeatures -.->|"leaderboard cache"| node_redis
node_simulator -->|"updates prices"| node_repositories
node_simulator -->|"publishes prices"| node_websocket
node_websocket -->|"streams prices"| node_pricehook
node_pricehook -->|"updates UI"| node_browser
node_rest -->|"JSON responses"| node_browser

click node_pages "https://github.com/adithyasai3/marketplay/tree/main/frontend/src/pages"
click node_app "https://github.com/adithyasai3/marketplay/blob/main/frontend/src/App.tsx"
click node_authcontext "https://github.com/adithyasai3/marketplay/blob/main/frontend/src/context/AuthContext.tsx"
click node_apiclient "https://github.com/adithyasai3/marketplay/blob/main/frontend/src/api/client.ts"
click node_featureapis "https://github.com/adithyasai3/marketplay/tree/main/frontend/src/api"
click node_pricehook "https://github.com/adithyasai3/marketplay/blob/main/frontend/src/hooks/useStockPrices.ts"
click node_rest "https://github.com/adithyasai3/marketplay/tree/main/backend/src/main/java/com/marketplay/controller"
click node_auth "https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/AuthService.java"
click node_jwt "https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/security/JwtService.java"
click node_stockservice "https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/StockService.java"
click node_trade "https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/TradeService.java"
click node_portfolio "https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/PortfolioService.java"
click node_otherfeatures "https://github.com/adithyasai3/marketplay/tree/main/backend/src/main/java/com/marketplay/service"
click node_repositories "https://github.com/adithyasai3/marketplay/tree/main/backend/src/main/java/com/marketplay/repository"
click node_simulator "https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/StockPriceSimulatorService.java"
click node_websocket "https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/config/WebSocketConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pages,node_app,node_authcontext,node_apiclient,node_featureapis,node_pricehook,node_browser toneBlue
class node_rest,node_auth,node_jwt,node_stockservice,node_trade,node_portfolio,node_otherfeatures toneAmber
class node_simulator,node_websocket toneMint
class node_repositories,node_postgres,node_redis toneRose
class node_user toneIndigo
```

## Components

### React application

- [Feature pages](https://github.com/adithyasai3/marketplay/tree/main/frontend/src/pages): `frontend/src/pages`
- [Route access](https://github.com/adithyasai3/marketplay/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/adithyasai3/marketplay/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [API client](https://github.com/adithyasai3/marketplay/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Resource APIs](https://github.com/adithyasai3/marketplay/tree/main/frontend/src/api): `frontend/src/api`
- [Live price hook](https://github.com/adithyasai3/marketplay/blob/main/frontend/src/hooks/useStockPrices.ts): `frontend/src/hooks/useStockPrices.ts`

### API and domain

- [REST controllers](https://github.com/adithyasai3/marketplay/tree/main/backend/src/main/java/com/marketplay/controller): `backend/src/main/java/com/marketplay/controller`
- [Authentication](https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/AuthService.java): `backend/src/main/java/com/marketplay/service/AuthService.java`
- [JWT security](https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/security/JwtService.java): `backend/src/main/java/com/marketplay/security/JwtService.java`
- [Stock catalog](https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/StockService.java): `backend/src/main/java/com/marketplay/service/StockService.java`
- [Trade execution](https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/TradeService.java): `backend/src/main/java/com/marketplay/service/TradeService.java`
- [Portfolio analytics](https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/PortfolioService.java): `backend/src/main/java/com/marketplay/service/PortfolioService.java`
- [Other services](https://github.com/adithyasai3/marketplay/tree/main/backend/src/main/java/com/marketplay/service): `backend/src/main/java/com/marketplay/service`

### Market updates

- [Price simulator](https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/service/StockPriceSimulatorService.java): `backend/src/main/java/com/marketplay/service/StockPriceSimulatorService.java`
- [WebSocket updates](https://github.com/adithyasai3/marketplay/blob/main/backend/src/main/java/com/marketplay/config/WebSocketConfig.java): `backend/src/main/java/com/marketplay/config/WebSocketConfig.java`

### Persistent state

- [Data repositories](https://github.com/adithyasai3/marketplay/tree/main/backend/src/main/java/com/marketplay/repository): `backend/src/main/java/com/marketplay/repository`
- **PostgreSQL**
- **Redis cache**

### Other components

- **Investor or admin**
- **Browser client**

## Connections

- Investor or admin → Route access: uses
- Route access → Feature pages: routes
- Feature pages → Auth context: uses auth
- Feature pages → Resource APIs: requests data
- Auth context → Resource APIs: auth requests
- Resource APIs → API client: uses
- API client → REST controllers: HTTP requests
- REST controllers → Authentication: delegates auth
- Authentication → JWT security: creates tokens
- REST controllers → Stock catalog: stock operations
- REST controllers → Trade execution: buy, sell, history
- REST controllers → Portfolio analytics: portfolio requests
- REST controllers → Other services: feature requests
- Trade execution → Stock catalog: looks up stock
- Trade execution → Data repositories: reads and writes
- Portfolio analytics → Data repositories: reads holdings
- Authentication → Data repositories: reads and writes
- Stock catalog → Data repositories: reads and writes
- Other services → Data repositories: feature state
- Data repositories → PostgreSQL: persists state
- Other services → Redis cache: leaderboard cache
- Price simulator → Data repositories: updates prices
- Price simulator → WebSocket updates: publishes prices
- WebSocket updates → Live price hook: streams prices
- Live price hook → Browser client: updates UI
- REST controllers → Browser client: JSON responses