# nabia-faisal/stock-exchange architecture

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

- Interactive diagram: https://gitdiagram.com/nabia-faisal/stock-exchange
- Repository: https://github.com/nabia-faisal/stock-exchange

## Overview

#### Purpose and entry points
NUST Exchange is a stateful JavaFX desktop stock-exchange simulator: authenticated traders submit market/limit buy and sell orders, which are matched into trades while prices and bot activity run in the background. Launch through `src/main/java/com/nust/exchange/app/Main.java`; JavaFX lifecycle and application composition are in `src/main/java/com/nust/exchange/app/App.java`.

#### Application shell and UI boundary
JavaFX views are the presentation boundary: login/registration occurs in `src/main/java/com/nust/exchange/ui/LoginView.java`, and the authenticated trading/dashboard experience is in `src/main/java/com/nust/exchange/ui/DashboardView.java`. UI actions should enter the exchange/domain APIs rather than mutate books, portfolios, or persistence directly. Styling is packaged at `src/main/resources/styles.css`.

#### Exchange orchestration
`src/main/java/com/nust/exchange/engine/Exchange.java` is the central market coordinator/singleton. It owns or coordinates listed stocks, traders, order submission, matching, market listeners, startup seeding/loading, and shutdown persistence. It forms the boundary between UI/background actors and mutable trading state.

#### Trading domain and order lifecycle
Orders are represented by `src/main/java/com/nust/exchange/model/Order.java` with distinct `MarketOrder.java` and `LimitOrder.java`; creation is centralized by `src/main/java/com/nust/exchange/patterns/OrderFactory.java`. Order side, type, and lifecycle status reside in `src/main/java/com/nust/exchange/enums/OrderSide.java`, `OrderType.java`, and `OrderStatus.java`. Validation failures are expressed through the trading exception hierarchy under `src/main/java/com/nust/exchange/exceptions/`.

#### Matching and settlement
`src/main/java/com/nust/exchange/engine/OrderBook.java` maintains executable order-book state/depth. `src/main/java/com/nust/exchange/engine/MatchingEngine.java` applies price-time priority, supports partial fills, and emits `src/main/java/com/nust/exchange/model/Trade.java`. Executions update buyer/seller cash and inventory through `src/main/java/com/nust/exchange/model/Portfolio.java` and `Holding.java`; this is the critical conservation and synchronization boundary.

#### Actors and live market processes
Trader variants—base `src/main/java/com/nust/exchange/model/Trader.java`, plus retail, institutional, and admin subclasses—define account capabilities. `src/main/java/com/nust/exchange/engine/PriceSimulator.java` updates market prices, while `BotTrader.java` creates automated order flow concurrently. Market changes are propagated through the observer interface `src/main/java/com/nust/exchange/patterns/MarketListener.java`; consumers include the UI.

#### Persistence and runtime infrastructure
State is disk-backed in the repository-local `data/` directory. `src/main/java/com/nust/exchange/persistence/DataStore.java` coordinates persistence; CSV repositories/mappers persist stocks and trades, while `BinaryRepository.java` serializes trader/account state. `TransactionLogger.java` appends trade audit records. The runtime is Java 17+ (documented Java 21 execution), JavaFX 21, Maven (`pom.xml`), with no network service or database dependency.

Main entry points: [`src/main/java/com/nust/exchange/engine/Exchange.java`](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/Exchange.java) (Exchange), [`src/main/java/com/nust/exchange/app/App.java`](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/app/App.java) (App), [`src/main/java/com/nust/exchange/engine/MatchingEngine.java`](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/MatchingEngine.java) (MatchingEngine), [`src/main/java/com/nust/exchange/ui/DashboardView.java`](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/ui/DashboardView.java) (DashboardView)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["JavaFX UI"]
  node_main["Main<br/>launcher<br/>[Main.java]"]
  node_app["App<br/>JavaFX composition<br/>[App.java]"]
  node_login["LoginView<br/>authentication UI<br/>[LoginView.java]"]
  node_dashboard["DashboardView<br/>trading UI<br/>[DashboardView.java]"]
end

subgraph group_market["Market Core"]
  node_exchange{{"Exchange<br/>market coordinator<br/>[Exchange.java]"}}
  node_order_factory["OrderFactory<br/>order creation<br/>[OrderFactory.java]"]
  node_orders["Orders<br/>[Order.java]"]
  node_order_book["OrderBook<br/>book state<br/>[OrderBook.java]"]
  node_matcher{{"MatchingEngine<br/>execution engine"}}
  node_trade["Trade<br/>execution record<br/>[Trade.java]"]
  node_portfolio["Portfolio &amp; Holding<br/>settlement state<br/>[Portfolio.java]"]
  node_listener["MarketListener<br/>observer interface"]
end

subgraph group_actors["Market Actors"]
  node_traders["Traders<br/>accounts and roles<br/>[Trader.java]"]
  node_price_sim(("PriceSimulator<br/>market process"))
  node_bot(("BotTrader<br/>automated actor<br/>[BotTrader.java]"))
end

subgraph group_storage["Persistence"]
  node_datastore[("DataStore<br/>persistence coordinator<br/>[DataStore.java]")]
  node_repositories[("CSV &amp; Binary repositories<br/>state repositories")]
  node_audit["TransactionLogger<br/>trade audit log"]
  node_disk[("data<br/>local disk state")]
end

node_main -->|"launches"| node_app
node_app -->|"composes"| node_login
node_app -->|"composes"| node_dashboard
node_login -->|"authenticates through"| node_exchange
node_dashboard -->|"trading actions"| node_exchange
node_exchange -->|"creates orders"| node_order_factory
node_order_factory -->|"builds"| node_orders
node_exchange -->|"submits to"| node_order_book
node_order_book -->|"executable orders"| node_matcher
node_matcher -->|"emits"| node_trade
node_matcher -->|"settles"| node_portfolio
node_traders -->|"own"| node_portfolio
node_bot -->|"automated orders"| node_exchange
node_price_sim -->|"price updates"| node_exchange
node_exchange -->|"publishes market changes"| node_listener
node_listener -->|"updates"| node_dashboard
node_exchange -->|"loads and saves state"| node_datastore
node_datastore -->|"coordinates"| node_repositories
node_repositories -->|"persists"| node_disk
node_trade -->|"audit record"| node_audit
node_audit -->|"appends"| node_disk

click node_main "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/app/Main.java"
click node_app "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/app/App.java"
click node_login "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/ui/LoginView.java"
click node_dashboard "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/ui/DashboardView.java"
click node_exchange "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/Exchange.java"
click node_order_factory "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/patterns/OrderFactory.java"
click node_orders "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/model/Order.java"
click node_order_book "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/OrderBook.java"
click node_matcher "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/MatchingEngine.java"
click node_trade "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/model/Trade.java"
click node_portfolio "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/model/Portfolio.java"
click node_traders "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/model/Trader.java"
click node_price_sim "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/PriceSimulator.java"
click node_bot "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/BotTrader.java"
click node_listener "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/patterns/MarketListener.java"
click node_datastore "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/persistence/DataStore.java"
click node_repositories "https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/persistence/BinaryRepository.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_main,node_app,node_login,node_dashboard toneBlue
class node_exchange,node_order_factory,node_orders,node_order_book,node_matcher,node_trade,node_portfolio,node_listener toneAmber
class node_traders,node_price_sim,node_bot toneMint
class node_datastore,node_repositories,node_audit,node_disk toneRose
```

## Components

### JavaFX UI

- [Main](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/app/Main.java): launcher · `src/main/java/com/nust/exchange/app/Main.java`
- [App](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/app/App.java): JavaFX composition · `src/main/java/com/nust/exchange/app/App.java`
- [LoginView](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/ui/LoginView.java): authentication UI · `src/main/java/com/nust/exchange/ui/LoginView.java`
- [DashboardView](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/ui/DashboardView.java): trading UI · Displays authenticated market activity and submits user actions. · `src/main/java/com/nust/exchange/ui/DashboardView.java`

### Market Core

- [Exchange](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/Exchange.java): market coordinator · Singleton boundary for mutable market state and lifecycle. · `src/main/java/com/nust/exchange/engine/Exchange.java`
- [OrderFactory](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/patterns/OrderFactory.java): order creation · `src/main/java/com/nust/exchange/patterns/OrderFactory.java`
- [Orders](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/model/Order.java): market and limit orders · Order lifecycle uses side, type, and status enums. · `src/main/java/com/nust/exchange/model/Order.java`
- [OrderBook](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/OrderBook.java): book state · Maintains executable orders and depth. · `src/main/java/com/nust/exchange/engine/OrderBook.java`
- [MatchingEngine](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/MatchingEngine.java): execution engine · Applies price-time priority and partial fills. · `src/main/java/com/nust/exchange/engine/MatchingEngine.java`
- [Trade](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/model/Trade.java): execution record · `src/main/java/com/nust/exchange/model/Trade.java`
- [Portfolio & Holding](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/model/Portfolio.java): settlement state · Cash and inventory update at the execution boundary. · `src/main/java/com/nust/exchange/model/Portfolio.java`
- [MarketListener](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/patterns/MarketListener.java): observer interface · `src/main/java/com/nust/exchange/patterns/MarketListener.java`

### Market Actors

- [Traders](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/model/Trader.java): accounts and roles · Base trader with retail, institutional, and admin variants. · `src/main/java/com/nust/exchange/model/Trader.java`
- [PriceSimulator](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/PriceSimulator.java): market process · `src/main/java/com/nust/exchange/engine/PriceSimulator.java`
- [BotTrader](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/engine/BotTrader.java): automated actor · Generates concurrent automated order flow. · `src/main/java/com/nust/exchange/engine/BotTrader.java`

### Persistence

- [DataStore](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/persistence/DataStore.java): persistence coordinator · `src/main/java/com/nust/exchange/persistence/DataStore.java`
- [CSV & Binary repositories](https://github.com/nabia-faisal/stock-exchange/blob/main/src/main/java/com/nust/exchange/persistence/BinaryRepository.java): state repositories · CSV persists stocks and trades; binary serialization persists accounts. · `src/main/java/com/nust/exchange/persistence/BinaryRepository.java`
- **TransactionLogger**: trade audit log
- **data**: local disk state · Repository-local persisted exchange state.

## Connections

- Main → App: launches
- App → LoginView: composes
- App → DashboardView: composes
- LoginView → Exchange: authenticates through
- DashboardView → Exchange: trading actions
- Exchange → OrderFactory: creates orders
- OrderFactory → Orders: builds
- Exchange → OrderBook: submits to
- OrderBook → MatchingEngine: executable orders
- MatchingEngine → Trade: emits
- MatchingEngine → Portfolio & Holding: settles
- Traders → Portfolio & Holding: own
- BotTrader → Exchange: automated orders
- PriceSimulator → Exchange: price updates
- Exchange → MarketListener: publishes market changes
- MarketListener → DashboardView: updates
- Exchange → DataStore: loads and saves state
- DataStore → CSV & Binary repositories: coordinates
- CSV & Binary repositories → data: persists
- Trade → TransactionLogger: audit record
- TransactionLogger → data: appends