# nvxtien/emporia architecture

> Architecture diagram of the GitHub repository nvxtien/emporia, 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/nvxtien/emporia
- Repository: https://github.com/nvxtien/emporia

## Overview

Emporia is a distributed trading platform whose browser workflow passes through a single gateway to authentication and capability-owning services. Order intake is the central runtime path: the OMS processes commands through its Disruptor hot path, maintains order lifecycle state, and routes execution in-process. Separate services provide market/reference data, preferences, and portfolio receipts. README statements support the cross-service links; source excerpts and the index expose selected internal calls, so unsampled internal wiring is not inferred.

Main entry points: [`market-data-service/src/main/java/com/emporia/marketdata/MarketDataService.java`](https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/MarketDataService.java) (Market data service), [`gateway/src/main/java/com/emporia/gateway/EmporiaGatewayApplication.java`](https://github.com/nvxtien/emporia/blob/main/gateway/src/main/java/com/emporia/gateway/EmporiaGatewayApplication.java) (API gateway), [`order-management-service/src/main/java/com/emporia/ordermanagement/controller/OrderCommandController.java`](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/controller/OrderCommandController.java) (Order API), [`order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderCommandHandler.java`](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderCommandHandler.java) (Order command handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and access"]
  node_workspace["Trading workspace"]
  node_gateway["API gateway"]
  node_auth["OIDC and users"]
end

subgraph group_reference["Reference and market data"]
  node_static["Instrument listings"]
  node_market["Market data service"]
  node_marketstream["Quote distribution"]
end

subgraph group_orders["Order lifecycle and execution"]
  node_omsapi["Order API"]
  node_pipeline["Disruptor pipeline"]
  node_handler["Order command handler"]
  node_state["Order state cache"]
  node_orderstore[("Order persistence")]
  node_routing["Execution routing"]
  node_strategies["SOR and VWAP"]
end

subgraph group_account["User and portfolio capabilities"]
  node_preferences["Watchlists and layouts"]
  node_portfolio["Portfolio receipts"]
end

subgraph group_integrations["External systems"]
  node_marketproviders["Market providers"]
  node_venues["Execution venues"]
  node_market_sources["Alpaca and FIX sources"]
  node_exchange_core["Exchange-core simulation"]
end

node_browser(("Trading user"))

node_browser -->|"uses"| node_workspace
node_workspace -->|"calls API"| node_gateway
node_gateway -->|"routes access"| node_auth
node_gateway -->|"routes requests"| node_static
node_gateway -->|"routes requests"| node_market
node_gateway -->|"routes orders"| node_omsapi
node_gateway -->|"routes requests"| node_preferences
node_market -->|"loads listings"| node_static
node_market -->|"gets quotes"| node_marketproviders
node_marketstream -->|"snapshots quotes"| node_market
node_marketstream -->|"resolves listings"| node_market
node_market_sources -->|"supplies prices"| node_market
node_omsapi -->|"submits commands"| node_pipeline
node_pipeline -->|"handles commands"| node_handler
node_handler -.->|"updates state"| node_state
node_handler -->|"persists asynchronously"| node_orderstore
node_omsapi -->|"validates listings"| node_static
node_routing -->|"selects strategy"| node_strategies
node_routing -.->|"dispatches execution"| node_venues
node_omsapi -->|"requests venue quotes"| node_market
node_exchange_core -->|"submits snapshots"| node_portfolio

click node_workspace "https://github.com/nvxtien/emporia/blob/main/frontend/src/components/TradingWorkspacePage.tsx"
click node_gateway "https://github.com/nvxtien/emporia/blob/main/gateway/src/main/java/com/emporia/gateway/EmporiaGatewayApplication.java"
click node_auth "https://github.com/nvxtien/emporia/blob/main/authentication/src/main/java/com/emporia/authentication/web/LoginController.java"
click node_static "https://github.com/nvxtien/emporia/blob/main/static-data-service/src/main/java/com/emporia/staticdata/InstrumentController.java"
click node_market "https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/MarketDataService.java"
click node_marketstream "https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/MarketDataStreamService.java"
click node_marketproviders "https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/MarketDataProvider.java"
click node_omsapi "https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/controller/OrderCommandController.java"
click node_pipeline "https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/disruptor/DisruptorOrderPipeline.java"
click node_handler "https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderCommandHandler.java"
click node_state "https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderStateCache.java"
click node_orderstore "https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/repository/TradingOrderRepository.java"
click node_routing "https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/execution/RoutingExecutionVenueGateway.java"
click node_strategies "https://github.com/nvxtien/emporia/blob/main/emporia-algorithmic-strategies/src/main/java/com/emporia/strategy/api/AlgorithmicExecutionStrategy.java"
click node_venues "https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/execution/ExecutionVenueGateway.java"
click node_preferences "https://github.com/nvxtien/emporia/blob/main/user-preferences-service/src/main/java/com/emporia/userpreferences/WatchlistService.java"
click node_portfolio "https://github.com/nvxtien/emporia/blob/main/portfolio-service/src/main/java/com/emporia/portfolio/PortfolioReceiptService.java"
click node_market_sources "https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/AlpacaIexMarketDataProvider.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_workspace,node_gateway,node_auth,node_browser toneBlue
class node_static,node_market,node_marketstream toneAmber
class node_omsapi,node_pipeline,node_handler,node_state,node_orderstore,node_routing,node_strategies toneMint
class node_preferences,node_portfolio toneRose
class node_marketproviders,node_venues,node_market_sources,node_exchange_core toneIndigo
```

## Components

### Web and access

- [Trading workspace](https://github.com/nvxtien/emporia/blob/main/frontend/src/components/TradingWorkspacePage.tsx): `frontend/src/components/TradingWorkspacePage.tsx`
- [API gateway](https://github.com/nvxtien/emporia/blob/main/gateway/src/main/java/com/emporia/gateway/EmporiaGatewayApplication.java): `gateway/src/main/java/com/emporia/gateway/EmporiaGatewayApplication.java`
- [OIDC and users](https://github.com/nvxtien/emporia/blob/main/authentication/src/main/java/com/emporia/authentication/web/LoginController.java): `authentication/src/main/java/com/emporia/authentication/web/LoginController.java`

### Reference and market data

- [Instrument listings](https://github.com/nvxtien/emporia/blob/main/static-data-service/src/main/java/com/emporia/staticdata/InstrumentController.java): `static-data-service/src/main/java/com/emporia/staticdata/InstrumentController.java`
- [Market data service](https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/MarketDataService.java): `market-data-service/src/main/java/com/emporia/marketdata/MarketDataService.java`
- [Quote distribution](https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/MarketDataStreamService.java): `market-data-service/src/main/java/com/emporia/marketdata/MarketDataStreamService.java`

### Order lifecycle and execution

- [Order API](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/controller/OrderCommandController.java): `order-management-service/src/main/java/com/emporia/ordermanagement/controller/OrderCommandController.java`
- [Disruptor pipeline](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/disruptor/DisruptorOrderPipeline.java): `order-management-service/src/main/java/com/emporia/ordermanagement/disruptor/DisruptorOrderPipeline.java`
- [Order command handler](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderCommandHandler.java): `order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderCommandHandler.java`
- [Order state cache](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderStateCache.java): `order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderStateCache.java`
- [Order persistence](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/ordermanagement/repository/TradingOrderRepository.java): `order-management-service/src/main/java/com/emporia/ordermanagement/repository/TradingOrderRepository.java`
- [Execution routing](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/execution/RoutingExecutionVenueGateway.java): `order-management-service/src/main/java/com/emporia/execution/RoutingExecutionVenueGateway.java`
- [SOR and VWAP](https://github.com/nvxtien/emporia/blob/main/emporia-algorithmic-strategies/src/main/java/com/emporia/strategy/api/AlgorithmicExecutionStrategy.java): `emporia-algorithmic-strategies/src/main/java/com/emporia/strategy/api/AlgorithmicExecutionStrategy.java`

### User and portfolio capabilities

- [Watchlists and layouts](https://github.com/nvxtien/emporia/blob/main/user-preferences-service/src/main/java/com/emporia/userpreferences/WatchlistService.java): `user-preferences-service/src/main/java/com/emporia/userpreferences/WatchlistService.java`
- [Portfolio receipts](https://github.com/nvxtien/emporia/blob/main/portfolio-service/src/main/java/com/emporia/portfolio/PortfolioReceiptService.java): `portfolio-service/src/main/java/com/emporia/portfolio/PortfolioReceiptService.java`

### External systems

- [Market providers](https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/MarketDataProvider.java): `market-data-service/src/main/java/com/emporia/marketdata/MarketDataProvider.java`
- [Execution venues](https://github.com/nvxtien/emporia/blob/main/order-management-service/src/main/java/com/emporia/execution/ExecutionVenueGateway.java): `order-management-service/src/main/java/com/emporia/execution/ExecutionVenueGateway.java`
- [Alpaca and FIX sources](https://github.com/nvxtien/emporia/blob/main/market-data-service/src/main/java/com/emporia/marketdata/AlpacaIexMarketDataProvider.java): `market-data-service/src/main/java/com/emporia/marketdata/AlpacaIexMarketDataProvider.java`
- **Exchange-core simulation**

### Other components

- **Trading user**

## Connections

- Trading user → Trading workspace: uses (evidence: `README.md`)
- Trading workspace → API gateway: calls API (evidence: `README.md`)
- API gateway → OIDC and users: routes access (evidence: `README.md`)
- API gateway → Instrument listings: routes requests (evidence: `README.md`)
- API gateway → Market data service: routes requests (evidence: `README.md`)
- API gateway → Order API: routes orders (evidence: `README.md`)
- API gateway → Watchlists and layouts: routes requests (evidence: `README.md`)
- Market data service → Instrument listings: loads listings (evidence: `README.md`)
- Market data service → Market providers: gets quotes (evidence: `market-data-service/src/main/java/com/emporia/marketdata/MarketDataService.java`)
- Quote distribution → Market data service: snapshots quotes (evidence: `market-data-service/src/main/java/com/emporia/marketdata/MarketDataStreamService.java`)
- Quote distribution → Market data service: resolves listings (evidence: `market-data-service/src/main/java/com/emporia/marketdata/MarketDataStreamService.java`)
- Alpaca and FIX sources → Market data service: supplies prices (evidence: `README.md`)
- Order API → Disruptor pipeline: submits commands (evidence: `README.md`)
- Disruptor pipeline → Order command handler: handles commands (evidence: `order-management-service/src/main/java/com/emporia/ordermanagement/disruptor/DisruptorOrderPipeline.java`)
- Order command handler → Order state cache: updates state (evidence: `order-management-service/src/main/java/com/emporia/ordermanagement/service/OrderCommandHandler.java`)
- Order command handler → Order persistence: persists asynchronously (evidence: `README.md`)
- Order API → Instrument listings: validates listings (evidence: `README.md`)
- Execution routing → SOR and VWAP: selects strategy (evidence: `README.md`)
- Execution routing → Execution venues: dispatches execution
- Order API → Market data service: requests venue quotes (evidence: `README.md`)
- Exchange-core simulation → Portfolio receipts: submits snapshots (evidence: `README.md`)
