# shawshank3/big-bull architecture

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

- Interactive diagram: https://gitdiagram.com/shawshank3/big-bull
- Repository: https://github.com/shawshank3/big-bull

## Overview

BigBull is a full-stack stock-market simulation platform: users register, receive virtual INR funds, browse simulated stock and mutual-fund prices, place trades, and review holdings, wallet activity, and tax outcomes. The React UI talks to an Express API; the market simulation updates prices and streams them to browsers. The README documents MongoDB, Redis, BullMQ, and optional Gemini-backed chat. Relationships for unsampled modules are included only where documented; source excerpts give more specific evidence for several API handlers.

Main entry points: [`apps/api/src/server.js`](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/server.js) (Express API), [`apps/api/src/modules/market/market.controller.js`](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/market/market.controller.js) (Market endpoints), [`apps/api/src/modules/portfolio/portfolio.controller.js`](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/portfolio/portfolio.controller.js) (Computed holdings), [`apps/ui/src/features/market`](https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/market) (Market browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser application"]
  node_ui["App routing<br/>[router.jsx]"]
  node_authui["Auth experience"]
  node_marketui["Market browser"]
  node_portui["Portfolio views"]
  node_taxui["Tax center"]
  node_chatui["Chat interface"]
end

subgraph group_api["API and identity"]
  node_apiapp["Express API<br/>[server.js]"]
  node_auth["Authentication<br/>[auth.controller.js]"]
  node_profile["User profile<br/>[user.controller.js]"]
end

subgraph group_trading["Trading and portfolio"]
  node_orders["Order execution"]
  node_wallet["Virtual wallet"]
  node_portfolio["Computed holdings"]
end

subgraph group_market["Market simulation"]
  node_marketapi["Market endpoints"]
  node_history["Charts and history"]
  node_simulation["Price simulation<br/>[mseWorker.js]"]
  node_daily["Daily price history"]
  node_sse["Live price stream"]
end

subgraph group_insights["Insights and tax"]
  node_tax["Tax analysis<br/>[tax.controller.js]"]
  node_chat["AI chat<br/>[chat.controller.js]"]
  node_insightsapi["Market insights"]
end

node_user(("Investor"))
node_mongo[("MongoDB")]
node_redis[("Redis")]
node_queue["BullMQ queue"]
node_gemini["Gemini service"]

node_user -->|"uses"| node_ui
node_ui -->|"routes to"| node_authui
node_authui -->|"REST requests"| node_apiapp
node_marketui -->|"REST requests"| node_apiapp
node_portui -->|"REST requests"| node_apiapp
node_taxui -->|"REST requests"| node_apiapp
node_chatui -->|"REST requests"| node_apiapp
node_apiapp -->|"mounts routes"| node_auth
node_apiapp -->|"mounts routes"| node_marketapi
node_apiapp -->|"mounts routes"| node_orders
node_apiapp -->|"mounts routes"| node_wallet
node_apiapp -->|"mounts routes"| node_portfolio
node_apiapp -->|"mounts routes"| node_tax
node_apiapp -->|"mounts routes"| node_chat
node_apiapp -->|"mounts routes"| node_insightsapi
node_apiapp -->|"mounts routes"| node_profile
node_auth -->|"seeds wallet"| node_wallet
node_auth -->|"loads identity"| node_profile
node_marketui -->|"receives prices"| node_sse
node_marketapi -->|"registers clients"| node_sse
node_simulation -->|"broadcasts updates"| node_sse
node_daily -->|"stores history"| node_mongo
node_simulation -->|"scheduled by"| node_queue
node_simulation -->|"caches prices"| node_redis
node_marketapi -->|"reads prices"| node_redis
node_marketapi -->|"serves charts"| node_history
node_orders -.->|"records trades"| node_portfolio
node_orders -.->|"updates balance"| node_wallet
node_portfolio -.->|"informs analysis"| node_tax
node_chat -.->|"requests answers"| node_gemini
node_taxui -->|"tax requests"| node_tax
node_marketui -->|"market requests"| node_marketapi
node_portui -->|"portfolio requests"| node_portfolio
node_chatui -->|"chat requests"| node_chat

click node_ui "https://github.com/shawshank3/big-bull/blob/main/apps/ui/src/app/router.jsx"
click node_authui "https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/auth"
click node_marketui "https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/market"
click node_portui "https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/portfolio"
click node_taxui "https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/tax"
click node_chatui "https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/chat"
click node_apiapp "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/server.js"
click node_auth "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/auth/auth.controller.js"
click node_profile "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/user/user.controller.js"
click node_marketapi "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/market/market.controller.js"
click node_history "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/market/chart.controller.js"
click node_simulation "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/workers/mseWorker.js"
click node_daily "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/workers/dailyPriceService.js"
click node_sse "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/market/market.controller.js"
click node_orders "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/transaction/transaction.controller.js"
click node_wallet "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/wallet/wallet.controller.js"
click node_portfolio "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/portfolio/portfolio.controller.js"
click node_tax "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/tax/tax.controller.js"
click node_chat "https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/chat/chat.controller.js"
click node_insightsapi "https://github.com/shawshank3/big-bull/tree/main/apps/api/src/modules/insights"

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_ui,node_authui,node_marketui,node_portui,node_taxui,node_chatui toneBlue
class node_apiapp,node_auth,node_profile,node_mongo,node_redis toneAmber
class node_orders,node_wallet,node_portfolio toneMint
class node_marketapi,node_history,node_simulation,node_daily,node_sse,node_queue toneRose
class node_tax,node_chat,node_insightsapi,node_user,node_gemini toneIndigo
```

## Components

### Browser application

- [App routing](https://github.com/shawshank3/big-bull/blob/main/apps/ui/src/app/router.jsx): `apps/ui/src/app/router.jsx`
- [Auth experience](https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/auth): `apps/ui/src/features/auth`
- [Market browser](https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/market): `apps/ui/src/features/market`
- [Portfolio views](https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/portfolio): `apps/ui/src/features/portfolio`
- [Tax center](https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/tax): `apps/ui/src/features/tax`
- [Chat interface](https://github.com/shawshank3/big-bull/tree/main/apps/ui/src/features/chat): `apps/ui/src/features/chat`

### API and identity

- [Express API](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/server.js): `apps/api/src/server.js`
- [Authentication](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/auth/auth.controller.js): `apps/api/src/modules/auth/auth.controller.js`
- [User profile](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/user/user.controller.js): `apps/api/src/modules/user/user.controller.js`

### Trading and portfolio

- [Order execution](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/transaction/transaction.controller.js): `apps/api/src/modules/transaction/transaction.controller.js`
- [Virtual wallet](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/wallet/wallet.controller.js): `apps/api/src/modules/wallet/wallet.controller.js`
- [Computed holdings](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/portfolio/portfolio.controller.js): `apps/api/src/modules/portfolio/portfolio.controller.js`

### Market simulation

- [Market endpoints](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/market/market.controller.js): `apps/api/src/modules/market/market.controller.js`
- [Charts and history](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/market/chart.controller.js): `apps/api/src/modules/market/chart.controller.js`
- [Price simulation](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/workers/mseWorker.js): `apps/api/src/workers/mseWorker.js`
- [Daily price history](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/workers/dailyPriceService.js): `apps/api/src/workers/dailyPriceService.js`
- [Live price stream](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/market/market.controller.js): `apps/api/src/modules/market/market.controller.js`

### Insights and tax

- [Tax analysis](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/tax/tax.controller.js): `apps/api/src/modules/tax/tax.controller.js`
- [AI chat](https://github.com/shawshank3/big-bull/blob/main/apps/api/src/modules/chat/chat.controller.js): `apps/api/src/modules/chat/chat.controller.js`
- [Market insights](https://github.com/shawshank3/big-bull/tree/main/apps/api/src/modules/insights): `apps/api/src/modules/insights`

### Other components

- **Investor**
- **MongoDB**
- **Redis**
- **BullMQ queue**
- **Gemini service**

## Connections

- Investor → App routing: uses (evidence: `README.md`)
- App routing → Auth experience: routes to (evidence: `apps/ui/src/app/router.jsx`)
- Auth experience → Express API: REST requests (evidence: `README.md`)
- Market browser → Express API: REST requests (evidence: `README.md`)
- Portfolio views → Express API: REST requests (evidence: `README.md`)
- Tax center → Express API: REST requests (evidence: `README.md`)
- Chat interface → Express API: REST requests (evidence: `README.md`)
- Express API → Authentication: mounts routes (evidence: `apps/api/src/server.js`)
- Express API → Market endpoints: mounts routes (evidence: `apps/api/src/server.js`)
- Express API → Order execution: mounts routes (evidence: `apps/api/src/server.js`)
- Express API → Virtual wallet: mounts routes (evidence: `apps/api/src/server.js`)
- Express API → Computed holdings: mounts routes (evidence: `apps/api/src/server.js`)
- Express API → Tax analysis: mounts routes (evidence: `apps/api/src/server.js`)
- Express API → AI chat: mounts routes (evidence: `apps/api/src/server.js`)
- Express API → Market insights: mounts routes (evidence: `apps/api/src/server.js`)
- Express API → User profile: mounts routes (evidence: `apps/api/src/server.js`)
- Authentication → Virtual wallet: seeds wallet (evidence: `apps/api/src/modules/auth/auth.controller.js`)
- Authentication → User profile: loads identity (evidence: `apps/api/src/modules/auth/auth.controller.js`)
- Market browser → Live price stream: receives prices (evidence: `README.md`)
- Market endpoints → Live price stream: registers clients (evidence: `apps/api/src/modules/market/market.controller.js`)
- Price simulation → Live price stream: broadcasts updates (evidence: `README.md`)
- Daily price history → MongoDB: stores history (evidence: `apps/api/src/workers/dailyPriceService.js`)
- Price simulation → BullMQ queue: scheduled by (evidence: `README.md`)
- Price simulation → Redis: caches prices (evidence: `README.md`)
- Market endpoints → Redis: reads prices (evidence: `apps/api/src/modules/market/market.controller.js`)
- Market endpoints → Charts and history: serves charts (evidence: `README.md`)
- Order execution → Computed holdings: records trades
- Order execution → Virtual wallet: updates balance
- Computed holdings → Tax analysis: informs analysis
- AI chat → Gemini service: requests answers
- Tax center → Tax analysis: tax requests (evidence: `README.md`)
- Market browser → Market endpoints: market requests (evidence: `README.md`)
- Portfolio views → Computed holdings: portfolio requests (evidence: `README.md`)
- Chat interface → AI chat: chat requests (evidence: `README.md`)
