# jack0dev/stocklab architecture

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

- Interactive diagram: https://gitdiagram.com/jack0dev/stocklab
- Repository: https://github.com/jack0dev/stocklab

## Overview

StockLab is a real-time stock-market trading simulator. Investors use the React client to authenticate, inspect prices and portfolios, and submit orders; backend services manage orders and matching, with results and account updates surfaced to the client. Major capabilities also include conditional orders, news, AI assistance, bot scenarios, wallet/VNPay flows, and an ML prediction service. Source excerpts establish selected matching, portfolio, authentication, stock, and crawler behavior; many other links below are dashed because their implementation was not sampled.

Main entry points: [`stocklab-frontend/src/presentation/pages`](https://github.com/jack0dev/stocklab/tree/master/stocklab-frontend/src/presentation/pages) (Product pages), [`stocklab-backend/src/main/java/com/stocklab/infrastructure/repository`](https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/infrastructure/repository) (Data repositories), [`stocklab-backend/src/main/java/com/stocklab/service/order`](https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/service/order) (Order services), [`stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/MatchingEngine.java`](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/MatchingEngine.java) (Matching engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["React application<br/>[App.jsx]"]
  node_pages["Product pages"]
  node_clientapi["API client<br/>[api.js]"]
end

subgraph group_trading["Trading and portfolios"]
  node_ordersvc["Order services"]
  node_matching["Matching engine"]
  node_trigger["Conditional orders<br/>[TriggerEngine.java]"]
  node_portfolios["Portfolio queries"]
  node_stocks["Stock data<br/>[StockService.java]"]
  node_tradingapi["Trading controllers"]
end

subgraph group_accounts["Accounts and money"]
  node_auth["Authentication and 2FA"]
  node_users["User security and profile"]
  node_wallet["Wallet and payments<br/>[WalletService.java]"]
  node_vnpay["VNPay integration<br/>[VnPayService.java]"]
end

subgraph group_insights["Insights and automation"]
  node_news["Financial news"]
  node_ai["AI assistant and RAG"]
  node_bot["Trading bot scenarios"]
  node_mlapi["ML prediction API<br/>[main.py]"]
  node_mlfeatures["ML features"]
  node_mltraining["Model training<br/>[train.py]"]
end

subgraph group_platform["Platform infrastructure"]
  node_repositories["Data repositories"]
  node_domain["Trading domain"]
  node_websocket["Live updates"]
end

node_investor(("Investor"))
node_mysql[("MySQL")]
node_redis[("Redis")]
node_aiproviders{{"Gemini and Ollama"}}

node_investor -->|"uses"| node_webapp
node_webapp -.->|"shows"| node_pages
node_pages -.->|"requests data"| node_clientapi
node_clientapi -.->|"calls REST"| node_tradingapi
node_tradingapi -.->|"delegates"| node_ordersvc
node_ordersvc -.->|"submits orders"| node_matching
node_matching -->|"reads and saves"| node_repositories
node_ordersvc -->|"reads and writes"| node_repositories
node_ordersvc -.->|"updates orders"| node_domain
node_trigger -.->|"dispatches triggered"| node_matching
node_portfolios -->|"queries holdings"| node_repositories
node_portfolios -->|"summarizes holdings"| node_domain
node_tradingapi -.->|"serves portfolio"| node_portfolios
node_pages -.->|"authenticates"| node_auth
node_auth -->|"loads users"| node_repositories
node_auth -.->|"verifies second factor"| node_users
node_users -.->|"loads accounts"| node_repositories
node_pages -.->|"manages balance"| node_wallet
node_wallet -.->|"initiates payment"| node_vnpay
node_pages -.->|"views prices"| node_stocks
node_stocks -->|"queries stock data"| node_repositories
node_news -->|"stores articles"| node_repositories
node_pages -.->|"browses news"| node_news
node_pages -.->|"asks questions"| node_ai
node_ai -.->|"queries models"| node_aiproviders
node_pages -.->|"manages campaigns"| node_bot
node_mlapi -.->|"uses features"| node_mlfeatures
node_mltraining -.->|"builds features"| node_mlfeatures
node_stocks -.->|"requests prediction"| node_mlapi
node_repositories -.->|"persists entities"| node_mysql
node_ordersvc -.->|"uses order cache"| node_redis
node_matching -.->|"publishes updates"| node_websocket
node_websocket -.->|"streams events"| node_webapp

click node_webapp "https://github.com/jack0dev/stocklab/blob/master/stocklab-frontend/src/App.jsx"
click node_pages "https://github.com/jack0dev/stocklab/tree/master/stocklab-frontend/src/presentation/pages"
click node_clientapi "https://github.com/jack0dev/stocklab/blob/master/stocklab-frontend/src/infrastructure/repositories/api.js"
click node_ordersvc "https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/service/order"
click node_matching "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/MatchingEngine.java"
click node_trigger "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/TriggerEngine.java"
click node_portfolios "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/order/PortfolioQueryService.java"
click node_stocks "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/StockService.java"
click node_tradingapi "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/presentation/controller/OrderController.java"
click node_auth "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/user/UserAuthService.java"
click node_users "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/user/UserSecurityService.java"
click node_wallet "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/WalletService.java"
click node_vnpay "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/VnPayService.java"
click node_news "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/NewsCrawlerService.java"
click node_ai "https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/service/ai"
click node_bot "https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/service/bot/manipulation"
click node_mlapi "https://github.com/jack0dev/stocklab/blob/master/stocklab-ml/api/main.py"
click node_mlfeatures "https://github.com/jack0dev/stocklab/blob/master/stocklab-ml/features/feature_engineering.py"
click node_mltraining "https://github.com/jack0dev/stocklab/blob/master/stocklab-ml/models/train.py"
click node_repositories "https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/infrastructure/repository"
click node_domain "https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/domain/model"
click node_websocket "https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/WebSocketService.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_webapp,node_pages,node_clientapi toneBlue
class node_ordersvc,node_matching,node_trigger,node_portfolios,node_stocks,node_tradingapi,node_mysql,node_redis toneAmber
class node_auth,node_users,node_wallet,node_vnpay toneMint
class node_news,node_ai,node_bot,node_mlapi,node_mlfeatures,node_mltraining toneRose
class node_repositories,node_domain,node_websocket,node_investor,node_aiproviders toneIndigo
```

## Components

### Web client

- [React application](https://github.com/jack0dev/stocklab/blob/master/stocklab-frontend/src/App.jsx): `stocklab-frontend/src/App.jsx`
- [Product pages](https://github.com/jack0dev/stocklab/tree/master/stocklab-frontend/src/presentation/pages): `stocklab-frontend/src/presentation/pages`
- [API client](https://github.com/jack0dev/stocklab/blob/master/stocklab-frontend/src/infrastructure/repositories/api.js): `stocklab-frontend/src/infrastructure/repositories/api.js`

### Trading and portfolios

- [Order services](https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/service/order): `stocklab-backend/src/main/java/com/stocklab/service/order`
- [Matching engine](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/MatchingEngine.java): `stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/MatchingEngine.java`
- [Conditional orders](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/TriggerEngine.java): `stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/TriggerEngine.java`
- [Portfolio queries](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/order/PortfolioQueryService.java): `stocklab-backend/src/main/java/com/stocklab/service/order/PortfolioQueryService.java`
- [Stock data](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/StockService.java): `stocklab-backend/src/main/java/com/stocklab/service/StockService.java`
- [Trading controllers](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/presentation/controller/OrderController.java): `stocklab-backend/src/main/java/com/stocklab/presentation/controller/OrderController.java`

### Accounts and money

- [Authentication and 2FA](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/user/UserAuthService.java): `stocklab-backend/src/main/java/com/stocklab/service/user/UserAuthService.java`
- [User security and profile](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/user/UserSecurityService.java): `stocklab-backend/src/main/java/com/stocklab/service/user/UserSecurityService.java`
- [Wallet and payments](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/WalletService.java): `stocklab-backend/src/main/java/com/stocklab/service/WalletService.java`
- [VNPay integration](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/VnPayService.java): `stocklab-backend/src/main/java/com/stocklab/service/VnPayService.java`

### Insights and automation

- [Financial news](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/NewsCrawlerService.java): `stocklab-backend/src/main/java/com/stocklab/service/NewsCrawlerService.java`
- [AI assistant and RAG](https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/service/ai): `stocklab-backend/src/main/java/com/stocklab/service/ai`
- [Trading bot scenarios](https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/service/bot/manipulation): `stocklab-backend/src/main/java/com/stocklab/service/bot/manipulation`
- [ML prediction API](https://github.com/jack0dev/stocklab/blob/master/stocklab-ml/api/main.py): `stocklab-ml/api/main.py`
- [ML features](https://github.com/jack0dev/stocklab/blob/master/stocklab-ml/features/feature_engineering.py): `stocklab-ml/features/feature_engineering.py`
- [Model training](https://github.com/jack0dev/stocklab/blob/master/stocklab-ml/models/train.py): `stocklab-ml/models/train.py`

### Platform infrastructure

- [Data repositories](https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/infrastructure/repository): `stocklab-backend/src/main/java/com/stocklab/infrastructure/repository`
- [Trading domain](https://github.com/jack0dev/stocklab/tree/master/stocklab-backend/src/main/java/com/stocklab/domain/model): `stocklab-backend/src/main/java/com/stocklab/domain/model`
- [Live updates](https://github.com/jack0dev/stocklab/blob/master/stocklab-backend/src/main/java/com/stocklab/service/WebSocketService.java): `stocklab-backend/src/main/java/com/stocklab/service/WebSocketService.java`

### Other components

- **Investor**
- **MySQL**
- **Redis**
- **Gemini and Ollama**

## Connections

- Investor → React application: uses
- React application → Product pages: shows
- Product pages → API client: requests data
- API client → Trading controllers: calls REST
- Trading controllers → Order services: delegates
- Order services → Matching engine: submits orders
- Matching engine → Data repositories: reads and saves (evidence: `stocklab-backend/src/main/java/com/stocklab/infrastructure/engine/MatchingEngine.java`)
- Order services → Data repositories: reads and writes (evidence: `stocklab-backend/src/main/java/com/stocklab/service/order/OrderManagementService.java`)
- Order services → Trading domain: updates orders (evidence: `stocklab-backend/src/main/java/com/stocklab/service/order/PortfolioQueryService.java`)
- Conditional orders → Matching engine: dispatches triggered
- Portfolio queries → Data repositories: queries holdings (evidence: `stocklab-backend/src/main/java/com/stocklab/service/order/PortfolioQueryService.java`)
- Portfolio queries → Trading domain: summarizes holdings (evidence: `stocklab-backend/src/main/java/com/stocklab/service/order/PortfolioQueryService.java`)
- Trading controllers → Portfolio queries: serves portfolio
- Product pages → Authentication and 2FA: authenticates
- Authentication and 2FA → Data repositories: loads users (evidence: `stocklab-backend/src/main/java/com/stocklab/service/user/UserAuthService.java`)
- Authentication and 2FA → User security and profile: verifies second factor
- User security and profile → Data repositories: loads accounts (evidence: `stocklab-backend/src/main/java/com/stocklab/service/user/UserSecurityService.java`)
- Product pages → Wallet and payments: manages balance
- Wallet and payments → VNPay integration: initiates payment
- Product pages → Stock data: views prices
- Stock data → Data repositories: queries stock data (evidence: `stocklab-backend/src/main/java/com/stocklab/service/StockService.java`)
- Financial news → Data repositories: stores articles (evidence: `stocklab-backend/src/main/java/com/stocklab/service/NewsCrawlerService.java`)
- Product pages → Financial news: browses news
- Product pages → AI assistant and RAG: asks questions
- AI assistant and RAG → Gemini and Ollama: queries models
- Product pages → Trading bot scenarios: manages campaigns
- ML prediction API → ML features: uses features
- Model training → ML features: builds features
- Stock data → ML prediction API: requests prediction
- Data repositories → MySQL: persists entities
- Order services → Redis: uses order cache
- Matching engine → Live updates: publishes updates
- Live updates → React application: streams events
