# swayamsahu/trading-engine-backend architecture

> Architecture diagram of the GitHub repository swayamsahu/trading-engine-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swayamsahu/trading-engine-backend
- Repository: https://github.com/swayamsahu/trading-engine-backend

## Overview

##### Project type and purpose
- This is a standalone backend service (a command-line trading engine) written in TypeScript that reads a JSON file of orders for the BTC/USDC pair, matches buy and sell orders, and writes out an order book, trades log, and structured logs.
- It’s not a full-stack web app but rather a modular compute engine with clear input (orders.json), processing components, and output files (orderbook.json, trades.json, trading.log).

##### File structure
- Top level:
- package.json, tsconfig.json, jest.config.js, .gitignore – build/test/config files
- orders.json – input data
- src/ folder:
- config.ts – central constants (file paths, trading pair)
- engine.ts – orchestration entry point
- fileIO.ts – reading orders.json, writing outputs
- validator.ts – input validation logic
- orderProcessor.ts – matching engine, order-book in memory, trade generation
- logger.ts – structured logging to file/console
- types.ts – shared interfaces/enums
- tests/ folder: unit tests for engine, validator, orderProcessor

##### README for architectural insights
- The README explicitly calls out five modules: TradingEngine (engine.ts), OrderProcessor, FileIO, Logger, OrderValidator, plus Config and Types as supporting components.
- It highlights single-responsibility design, modularity, testability, extensibility.

##### Main components and their roles
a. Input/Output layer
- FileIO Module
- orders.json (input)
- orderbook.json & trades.json (output)
- trading.log (structured logs)
b. Core processing
- Engine (engine.ts): orchestrates overall workflow
- Validator (validator.ts): rejects or passes orders
- OrderProcessor (orderProcessor.ts): maintains in-memory order book, performs matching, emits trade records
c. Supporting modules
- Logger (logger.ts): writes INFO/WARN/ERROR messages
- Config (config.ts): file paths, constants
- Types (types.ts): TypeScript interfaces and enums
d. Testing & Tooling
- Jest tests under tests/
- ESLint (via package.json scripts)
- TypeScript compiler (tsconfig.json)

##### Relationships and data-flow
1) Engine starts → reads config → invokes FileIO to read orders.json
2) For each order:
→ pass to Validator → if valid, forward to OrderProcessor → update in-memory book & generate trade(s)
→ log each step via Logger
3) After all orders processed → Engine calls FileIO to write orderbook.json & trades.json
4) Throughout, Logger writes to trading.log & console

##### Architectural patterns and design principles
- Single Responsibility: every module does one thing
- Layered architecture: I/O layer, validation layer, business logic layer, logging
- In-memory data store for order book, persisted only at end of run
- Testable, modular code

## Diagram (Mermaid)

```mermaid
graph TD
    %% File I/O Layer
    subgraph "File I/O Layer"
        IO_FileIO["File I/O Module<br/>(fileIO.ts)"]:::io
        IO_Orders["orders.json"]:::file
    end

    %% Processing Layer
    subgraph "Processing Layer"
        P_Engine["TradingEngine<br/>(engine.ts)"]:::compute
        P_Validator["OrderValidator<br/>(validator.ts)"]:::compute
        P_Processor["OrderProcessor<br/>(orderProcessor.ts)"]:::compute
        P_OrderBook["In-Memory OrderBook"]:::data
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        S_Config["Config<br/>(config.ts)"]:::support
        S_Types["Types<br/>(types.ts)"]:::support
        S_Logger["Logger Module<br/>(logger.ts)"]:::logger
    end

    %% Outputs
    subgraph "Output Layer"
        Out_Trades["trades.json"]:::file
        Out_OrderBook["orderbook.json"]:::file
        Out_Log["trading.log"]:::file
    end

    %% Tooling
    subgraph "Testing & Tooling"
        T_EngineTest["Engine Tests<br/>(engine.test.ts)"]:::test
    end

    %% Data Flows
    IO_Orders -->|"Order[]"| IO_FileIO
    IO_FileIO -->|"Parsed Orders"| P_Engine
    P_Engine -->|"Order"| P_Validator
    P_Validator -->|"ValidatedOrder"| P_Processor
    P_Processor -->|"updates"| P_OrderBook
    P_Processor -->|"Trade[] & UpdatedBook"| IO_FileIO
    IO_FileIO -->|"writes trades"| Out_Trades
    IO_FileIO -->|"writes orderbook"| Out_OrderBook

    %% Logging
    P_Engine -.->|"logs"| S_Logger
    P_Validator -.->|"logs"| S_Logger
    P_Processor -.->|"logs"| S_Logger
    S_Logger -->|"writes logs"| Out_Log

    %% Dependencies
    S_Config --> P_Engine
    S_Config --> P_Validator
    S_Config --> P_Processor
    S_Config --> IO_FileIO
    S_Config --> S_Logger
    S_Types --> P_Engine
    S_Types --> P_Validator
    S_Types --> P_Processor
    S_Types --> IO_FileIO

    %% Testing linkage
    T_EngineTest --> P_Engine

    %% Click events
    click P_Engine "https://github.com/swayamsahu/trading-engine-backend/blob/main/src/engine.ts"
    click P_Validator "https://github.com/swayamsahu/trading-engine-backend/blob/main/src/validator.ts"
    click P_Processor "https://github.com/swayamsahu/trading-engine-backend/blob/main/src/orderProcessor.ts"
    click IO_FileIO "https://github.com/swayamsahu/trading-engine-backend/blob/main/src/fileIO.ts"
    click S_Logger "https://github.com/swayamsahu/trading-engine-backend/blob/main/src/logger.ts"
    click S_Config "https://github.com/swayamsahu/trading-engine-backend/blob/main/src/config.ts"
    click S_Types "https://github.com/swayamsahu/trading-engine-backend/blob/main/src/types.ts"
    click IO_Orders "https://github.com/swayamsahu/trading-engine-backend/blob/main/orders.json"
    click T_EngineTest "https://github.com/swayamsahu/trading-engine-backend/blob/main/tests/engine.test.ts"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef io fill:#E6F4EA,stroke:#22863A,stroke-width:1px;
    classDef logger fill:#FFF5D1,stroke:#E36209,stroke-width:1px;
    classDef data fill:#F0E6FF,stroke:#6F42C1,stroke-width:1px;
    classDef file fill:#F5F5F5,stroke:#586069,stroke-width:1px,stroke-dasharray: 2 2;
    classDef support fill:#F0F0F0,stroke:#888,stroke-width:1px;
    classDef test fill:#FFF0F6,stroke:#CB2431,stroke-width:1px;
```
