nabia-faisal/stock-exchange

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.