# finos/traderx architecture

> Architecture diagram of the GitHub repository finos/traderx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/finos/traderx
- Repository: https://github.com/finos/traderx

## Overview

##### Project type and purpose
- This is a distributed, polyglot, full-stack reference trading application (“TraderX”) designed as a microservices demo.
- It showcases RESTful services (Java/Spring Boot, .NET Core, Node/NestJS), a message bus (Socket.IO), an embedded SQL database, and two front-end UIs (Angular & React).

##### File structure
- Top-level service directories:
- database (Java/H2)
- reference-data (Node/NestJS)
- trade-feed (Node/Socket.IO message bus)
- people-service (.NET Core)
- account-service (Java/Spring Boot)
- -service (Java/Spring Boot)
- trade-service (Java/Spring Boot)
- trade-processor (Java/Spring Boot subscriber/processor)
- web-front-end (Angular & React)
- Deployment/config: Dockerfiles, docker-compose.yml, Kustomize under gitops, Tiltfile for Kubernetes.

##### Key insights from the README
- Services communicate over HTTP/REST and a pub/sub bus
- Default ports for each component and recommended startup sequence
- Support for Docker Compose and Kubernetes via gitops/kustomize/Tiltfile

##### Main components
A. Database layer
- H2 SQL database container (database)
B. Microservices layer (RESTful)
- Reference-Data Service (Node/NestJS)
- People Service (.NET Core)
- Account Service (Java/Spring Boot)
- Service (Java/Spring Boot)
- Trade Service (Java/Spring Boot)
C. Message Bus layer
- Trade-Feed (Socket.IO publisher)
- Trade-Processor (Socket.IO subscriber + processing)
D. Front-end UI
- Angular App (full account/trade UI)
- React App (trade/blotter UI)
E. Ingress/API gateway (nginx ingress via Kubernetes or Docker Compose)
F. Optional: GitOps/K8s Control Plane (Tilt/Kustomize)

##### Relationships and interactions
- Front-end → HTTP REST → Reference-Data, People, Account, Position, Trade Services
- Trade Service → publishes to Socket.IO bus (Trade-Feed)
- Trade-Feed → real-time broadcast → UI clients (Angular/React)
- Trade-Processor → subscribes to Socket.IO bus, processes orders, writes to DB, updates Position Service
- Service → queries DB / repository for positions & executed trades
- All Java services talk to the central SQL database for persistence
- Ingress sits in front of all services for unified routing

##### Architectural patterns & design principles
- Microservices: each bounded context in its own container, own codebase
- Polyglot services: choose best-fit runtimes (Java, .NET, Node)
- Pub/Sub event distribution: Socket.IO bus for real-time updates
- Containerized deployments + Docker Compose or Kubernetes + GitOps
- Clear separation of API (REST) vs messaging

##### Final checklist
- All components clearly labeled and grouped
- Optional: annotate ports or config files for clarity
- Keep it detailed but avoid clutter—focus on logical interactions and data flows.
- Refer to existing C4 DSL in docs/c4 as a starting point for style and notation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        Angular["Angular App"]:::frontendAngular
        React["React App"]:::frontendReact
    end

    %% Ingress/API Gateway
    subgraph "Ingress/API Gateway"
        Ingress["Nginx Ingress"]:::gateway
    end

    %% Microservices Layer
    subgraph "Microservices"
        RefData["Reference-Data Service\n(Node/NestJS)"]:::node
        People["People Service\n(.NET Core)"]:::dotnet
        Account["Account Service\n(Java/Spring Boot)"]:::java
        Position["Position Service\n(Java/Spring Boot)"]:::java
        Trade["Trade Service\n(Java/Spring Boot)"]:::java
    end

    %% Messaging Layer
    subgraph "Message Bus Layer"
        TradeFeed["Trade-Feed\n(Socket.IO bus)"]:::messaging
        TradeProc["Trade-Processor\n(Socket.IO subscriber)"]:::java
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["H2 SQL Database"]:::db
    end

    %% Deployment Config
    subgraph "GitOps / K8s Config"
        GitOps["GitOps Config"]:::gitops
    end

    %% Relationships
    Angular -->|"HTTP REST"| Ingress
    React -->|"HTTP REST"| Ingress

    Ingress -->|"REST"| RefData
    Ingress -->|"REST"| People
    Ingress -->|"REST"| Account
    Ingress -->|"REST"| Position
    Ingress -->|"REST"| Trade

    Trade -->|"publishes"| TradeFeed
    TradeFeed -->|"broadcasts"| Angular
    TradeFeed -->|"broadcasts"| React

    TradeProc -->|"subscribes"| TradeFeed
    TradeProc -->|"writes to"| DB
    Position -->|"queries"| DB
    Account -->|"persist"| DB
    Trade -->|"persist"| DB
    RefData -->|"persist"| DB
    People -->|"persist"| DB

    GitOps -.-> Ingress
    GitOps -.-> RefData
    GitOps -.-> People
    GitOps -.-> Account
    GitOps -.-> Position
    GitOps -.-> Trade
    GitOps -.-> TradeFeed
    GitOps -.-> TradeProc
    GitOps -.-> Angular
    GitOps -.-> React
    GitOps -.-> DB

    %% Click Events
    click DB "https://github.com/finos/traderx/tree/main/database/"
    click RefData "https://github.com/finos/traderx/tree/main/reference-data/"
    click People "https://github.com/finos/traderx/tree/main/people-service/"
    click Account "https://github.com/finos/traderx/tree/main/account-service/"
    click Position "https://github.com/finos/traderx/tree/main/position-service/"
    click Trade "https://github.com/finos/traderx/tree/main/trade-service/"
    click TradeFeed "https://github.com/finos/traderx/tree/main/trade-feed/"
    click TradeProc "https://github.com/finos/traderx/tree/main/trade-processor/"
    click Angular "https://github.com/finos/traderx/tree/main/web-front-end/angular/"
    click React "https://github.com/finos/traderx/tree/main/web-front-end/react/"
    click Ingress "https://github.com/finos/traderx/tree/main/ingress/"
    click GitOps "https://github.com/finos/traderx/tree/main/gitops/"

    %% Styles
    classDef java fill:#f2a654,stroke:#e07b39
    classDef node fill:#a3be8c,stroke:#5e8a66
    classDef dotnet fill:#5e81ac,stroke:#2e3e5e
    classDef frontendAngular fill:#e34c26,stroke:#b32c1e
    classDef frontendReact fill:#61dafb,stroke:#21a1f1
    classDef db fill:#d8dee9,stroke:#4c566a
    classDef messaging fill:#b48ead,stroke:#7c5784
    classDef gateway fill:#eceff4,stroke:#4c566a,stroke-dasharray: 5 5
    classDef gitops fill:#ebcb8b,stroke:#b48ead,stroke-dasharray: 2 2
```
