# exxxotic-coder/stockflow architecture

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

- Interactive diagram: https://gitdiagram.com/exxxotic-coder/stockflow
- Repository: https://github.com/exxxotic-coder/stockflow

## Overview

StockFlow combines a public marketing and account-entry site, an authenticated virtual-trading dashboard, and an Express/MongoDB backend. The principal workflow is user signup or login, entry to the dashboard, then viewing market and portfolio data or placing virtual trades and managing funds; a chat assistant can answer portfolio questions and update holdings. Backend excerpts show chat orchestration, holdings access, price lookup, and Gemini fallback. Dashboard internals and several backend routes were not sampled, so documented links are identified as such rather than presented as inspected calls.

Main entry points: [`backend/index.js`](https://github.com/exxxotic-coder/stockflow/blob/main/backend/index.js) (REST API Server), [`dashboard/src/components/Home.js`](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Home.js) (Trading Console), [`backend/controllers/chatController.js`](https://github.com/exxxotic-coder/stockflow/blob/main/backend/controllers/chatController.js) (Chat Orchestrator), [`backend/routes/chatRoutes.js`](https://github.com/exxxotic-coder/stockflow/blob/main/backend/routes/chatRoutes.js) (Chat Route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Public Website"]
  node_site["Marketing Pages<br/>[index.js]"]
  node_account["Signup / Login<br/>[Signup.js]"]
end

subgraph group_trade["Trading Dashboard"]
  node_dashboard["Trading Console<br/>[Home.js]"]
  node_watchlist["Watchlist &amp; Market<br/>[WatchList.js]"]
  node_holdingsui["Holdings Portfolio<br/>[Holdings.js]"]
  node_positionsui["Open Positions<br/>[Positions.js]"]
  node_ordersui["Order History<br/>[Orders.js]"]
  node_fundsui["Virtual Funds<br/>[Funds.js]"]
  node_buyui["Trade Actions<br/>[BuyActionWindow.js]"]
  node_chatui["Assistant Widget<br/>[ChatWidget.js]"]
end

subgraph group_api["Backend Services"]
  node_server["REST API Server<br/>[index.js]"]
  node_auth["Session Authentication<br/>[auth.js]"]
  node_chatroute["Chat Route<br/>[chatRoutes.js]"]
  node_chat["Chat Orchestrator<br/>[chatController.js]"]
  node_intent["Intent Parser<br/>[intentService.js]"]
  node_holdingservice["Holdings Operations<br/>[holdingsService.js]"]
  node_positionorders["Position &amp; Order Queries"]
  node_prices["Live Price Service"]
  node_gemini["Gemini Adapter<br/>[geminiService.js]"]
end

subgraph group_data["Portfolio Data"]
  node_users[("User Records<br/>[UserModel.js]")]
  node_holdings[("Holdings Records<br/>[HoldingsModel.js]")]
  node_positions[("Positions Records<br/>[PositionsModel.js]")]
  node_orders[("Order Records<br/>[OrdersModel.js]")]
end

node_visitor(("Investor"))
node_yahoo{{"Yahoo Finance"}}
node_google{{"Google Gemini"}}

node_visitor -->|"visits"| node_site
node_visitor -->|"creates account"| node_account
node_account -->|"authenticates"| node_server
node_account -->|"forwards credentials"| node_dashboard
node_visitor -->|"uses console"| node_dashboard
node_dashboard -->|"shows market"| node_watchlist
node_dashboard -->|"shows portfolio"| node_holdingsui
node_dashboard -->|"shows positions"| node_positionsui
node_dashboard -->|"shows transactions"| node_ordersui
node_dashboard -->|"manages wallet"| node_fundsui
node_dashboard -->|"initiates trades"| node_buyui
node_dashboard -->|"opens assistant"| node_chatui
node_watchlist -.->|"requests prices"| node_server
node_holdingsui -.->|"loads holdings"| node_server
node_positionsui -.->|"loads positions"| node_server
node_ordersui -.->|"loads orders"| node_server
node_fundsui -.->|"updates balance"| node_server
node_buyui -.->|"submits trade"| node_server
node_chatui -.->|"sends message"| node_chatroute
node_server -->|"mounts routes"| node_chatroute
node_chatroute -->|"guards request"| node_auth
node_chatroute -->|"dispatches to"| node_chat
node_chat -->|"parses intent"| node_intent
node_chat -->|"queries or updates"| node_holdingservice
node_chat -->|"queries records"| node_positionorders
node_chat -->|"refreshes quotes"| node_prices
node_chat -->|"requests phrasing"| node_gemini
node_holdingservice -->|"reads and writes"| node_holdings
node_positionorders -->|"queries"| node_positions
node_positionorders -->|"queries"| node_orders
node_server -->|"auth and wallet data"| node_users
node_server -->|"serves holdings data"| node_holdings
node_server -->|"serves positions data"| node_positions
node_server -->|"serves orders data"| node_orders
node_server -->|"gets live quotes"| node_prices
node_prices -->|"fetches quotes"| node_yahoo
node_gemini -->|"generates reply"| node_google

click node_site "https://github.com/exxxotic-coder/stockflow/blob/main/frontend/src/index.js"
click node_account "https://github.com/exxxotic-coder/stockflow/blob/main/frontend/src/landing_page/signup/Signup.js"
click node_dashboard "https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Home.js"
click node_watchlist "https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/WatchList.js"
click node_holdingsui "https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Holdings.js"
click node_positionsui "https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Positions.js"
click node_ordersui "https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Orders.js"
click node_fundsui "https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Funds.js"
click node_buyui "https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/BuyActionWindow.js"
click node_chatui "https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/ChatWidget.js"
click node_server "https://github.com/exxxotic-coder/stockflow/blob/main/backend/index.js"
click node_auth "https://github.com/exxxotic-coder/stockflow/blob/main/backend/middleware/auth.js"
click node_chatroute "https://github.com/exxxotic-coder/stockflow/blob/main/backend/routes/chatRoutes.js"
click node_chat "https://github.com/exxxotic-coder/stockflow/blob/main/backend/controllers/chatController.js"
click node_intent "https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/intentService.js"
click node_holdingservice "https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/holdingsService.js"
click node_positionorders "https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/positionsOrdersService.js"
click node_prices "https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/livePriceService.js"
click node_gemini "https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/geminiService.js"
click node_users "https://github.com/exxxotic-coder/stockflow/blob/main/backend/model/UserModel.js"
click node_holdings "https://github.com/exxxotic-coder/stockflow/blob/main/backend/model/HoldingsModel.js"
click node_positions "https://github.com/exxxotic-coder/stockflow/blob/main/backend/model/PositionsModel.js"
click node_orders "https://github.com/exxxotic-coder/stockflow/blob/main/backend/model/OrdersModel.js"

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_site,node_account toneBlue
class node_dashboard,node_watchlist,node_holdingsui,node_positionsui,node_ordersui,node_fundsui,node_buyui,node_chatui toneAmber
class node_server,node_auth,node_chatroute,node_chat,node_intent,node_holdingservice,node_positionorders,node_prices,node_gemini toneMint
class node_users,node_holdings,node_positions,node_orders toneRose
class node_visitor,node_yahoo,node_google toneIndigo
```

## Components

### Public Website

- [Marketing Pages](https://github.com/exxxotic-coder/stockflow/blob/main/frontend/src/index.js): `frontend/src/index.js`
- [Signup / Login](https://github.com/exxxotic-coder/stockflow/blob/main/frontend/src/landing_page/signup/Signup.js): `frontend/src/landing_page/signup/Signup.js`

### Trading Dashboard

- [Trading Console](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Home.js): `dashboard/src/components/Home.js`
- [Watchlist & Market](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/WatchList.js): `dashboard/src/components/WatchList.js`
- [Holdings Portfolio](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Holdings.js): `dashboard/src/components/Holdings.js`
- [Open Positions](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Positions.js): `dashboard/src/components/Positions.js`
- [Order History](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Orders.js): `dashboard/src/components/Orders.js`
- [Virtual Funds](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/Funds.js): `dashboard/src/components/Funds.js`
- [Trade Actions](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/BuyActionWindow.js): `dashboard/src/components/BuyActionWindow.js`
- [Assistant Widget](https://github.com/exxxotic-coder/stockflow/blob/main/dashboard/src/components/ChatWidget.js): `dashboard/src/components/ChatWidget.js`

### Backend Services

- [REST API Server](https://github.com/exxxotic-coder/stockflow/blob/main/backend/index.js): `backend/index.js`
- [Session Authentication](https://github.com/exxxotic-coder/stockflow/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`
- [Chat Route](https://github.com/exxxotic-coder/stockflow/blob/main/backend/routes/chatRoutes.js): `backend/routes/chatRoutes.js`
- [Chat Orchestrator](https://github.com/exxxotic-coder/stockflow/blob/main/backend/controllers/chatController.js): `backend/controllers/chatController.js`
- [Intent Parser](https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/intentService.js): `backend/services/intentService.js`
- [Holdings Operations](https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/holdingsService.js): `backend/services/holdingsService.js`
- [Position & Order Queries](https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/positionsOrdersService.js): `backend/services/positionsOrdersService.js`
- [Live Price Service](https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/livePriceService.js): `backend/services/livePriceService.js`
- [Gemini Adapter](https://github.com/exxxotic-coder/stockflow/blob/main/backend/services/geminiService.js): `backend/services/geminiService.js`

### Portfolio Data

- [User Records](https://github.com/exxxotic-coder/stockflow/blob/main/backend/model/UserModel.js): `backend/model/UserModel.js`
- [Holdings Records](https://github.com/exxxotic-coder/stockflow/blob/main/backend/model/HoldingsModel.js): `backend/model/HoldingsModel.js`
- [Positions Records](https://github.com/exxxotic-coder/stockflow/blob/main/backend/model/PositionsModel.js): `backend/model/PositionsModel.js`
- [Order Records](https://github.com/exxxotic-coder/stockflow/blob/main/backend/model/OrdersModel.js): `backend/model/OrdersModel.js`

### Other components

- **Investor**
- **Yahoo Finance**
- **Google Gemini**

## Connections

- Investor → Marketing Pages: visits (evidence: `frontend/src/index.js`)
- Investor → Signup / Login: creates account (evidence: `README.md`)
- Signup / Login → REST API Server: authenticates (evidence: `README.md`)
- Signup / Login → Trading Console: forwards credentials (evidence: `README.md`)
- Investor → Trading Console: uses console (evidence: `README.md`)
- Trading Console → Watchlist & Market: shows market (evidence: `README.md`)
- Trading Console → Holdings Portfolio: shows portfolio (evidence: `README.md`)
- Trading Console → Open Positions: shows positions (evidence: `README.md`)
- Trading Console → Order History: shows transactions (evidence: `README.md`)
- Trading Console → Virtual Funds: manages wallet (evidence: `README.md`)
- Trading Console → Trade Actions: initiates trades (evidence: `README.md`)
- Trading Console → Assistant Widget: opens assistant (evidence: `README.md`)
- Watchlist & Market → REST API Server: requests prices
- Holdings Portfolio → REST API Server: loads holdings
- Open Positions → REST API Server: loads positions
- Order History → REST API Server: loads orders
- Virtual Funds → REST API Server: updates balance
- Trade Actions → REST API Server: submits trade
- Assistant Widget → Chat Route: sends message
- REST API Server → Chat Route: mounts routes (evidence: `backend/index.js`)
- Chat Route → Session Authentication: guards request (evidence: `backend/routes/chatRoutes.js`)
- Chat Route → Chat Orchestrator: dispatches to (evidence: `backend/routes/chatRoutes.js`)
- Chat Orchestrator → Intent Parser: parses intent (evidence: `backend/controllers/chatController.js`)
- Chat Orchestrator → Holdings Operations: queries or updates (evidence: `backend/controllers/chatController.js`)
- Chat Orchestrator → Position & Order Queries: queries records (evidence: `backend/controllers/chatController.js`)
- Chat Orchestrator → Live Price Service: refreshes quotes (evidence: `backend/controllers/chatController.js`)
- Chat Orchestrator → Gemini Adapter: requests phrasing (evidence: `backend/controllers/chatController.js`)
- Holdings Operations → Holdings Records: reads and writes (evidence: `backend/services/holdingsService.js`)
- Position & Order Queries → Positions Records: queries (evidence: `backend/services/positionsOrdersService.js`)
- Position & Order Queries → Order Records: queries (evidence: `backend/services/positionsOrdersService.js`)
- REST API Server → User Records: auth and wallet data (evidence: `backend/index.js`)
- REST API Server → Holdings Records: serves holdings data (evidence: `backend/index.js`)
- REST API Server → Positions Records: serves positions data (evidence: `backend/index.js`)
- REST API Server → Order Records: serves orders data (evidence: `backend/index.js`)
- REST API Server → Live Price Service: gets live quotes (evidence: `backend/index.js`)
- Live Price Service → Yahoo Finance: fetches quotes (evidence: `backend/services/livePriceService.js`)
- Gemini Adapter → Google Gemini: generates reply (evidence: `backend/services/geminiService.js`)