# deepak-meena-github/forex-trading-system architecture

> Architecture diagram of the GitHub repository deepak-meena-github/forex-trading-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deepak-meena-github/forex-trading-system
- Repository: https://github.com/deepak-meena-github/forex-trading-system

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is a **backend-only NestJS (Node.js/TypeScript) REST API** called **“Forex Trading System API”**. Its responsibilities (per README + endpoints) are:

- Expose HTTP endpoints for:
- Fetching **live FX rates** (`GET /fx-rates`)
- **Top-up** a user account (`POST /top-up/:userId`)
- Query **account balance** (`GET /balance/:userId`)
- Execute **FX conversion** (`POST /fx-conversion`)
- Integrate with **Alpha Vantage** (external API) using `ALPHA_VANTAGE_API_KEY`

- **API consumers → NestJS app → domain/service logic → external Alpha Vantage**
- Optional persistence (explicitly marked as “in-memory” if true, or “future DB” if intended)

##### Top-level
- `src/` → source code (Nest app)
- `dist/` → compiled JS output (deployment artifact)
- `test/` → e2e tests (Jest)
- `nest-cli.json`, `tsconfig*.json`, `package.json` → build/runtime configuration
- Swagger PDFs + README mention `/api` → Swagger/OpenAPI is part of the runtime (likely configured in `src/main.ts`)

##### `src/` (core runtime architecture)
- `main.ts`
- App bootstrap, global pipes/validation, Swagger setup, port binding.
- `app.module.ts`
- Nest module composition (providers/controllers).
- `app.controller.ts`
- Defines the REST endpoints. This is your **API layer**.
- `app.service.ts`
- Business logic: balances, top-ups, conversions, calling Alpha Vantage, and any “storage” logic present.
- `src/dto/*.dto.ts`
- `Account.dto.ts`, `FxConversion.dto.ts` represent **request/response schema + validation** boundaries.

##### Tests
- `src/app.controller.spec.ts` → unit tests around controller behavior
- `test/app.e2e-spec.ts` + `test/jest-e2e.json` → end-to-end tests that spin up the app

**Key architecture pattern:** classic NestJS layering:
**Controller (transport) → Service (domain/application logic) → External API (Alpha Vantage) → (Optional persistence)**

- “API Client(s)” (browser, mobile app, Postman, other service)
- “Forex Trading System API (NestJS)”
- “Alpha Vantage FX API” (external dependency)
- “Swagger UI (/api)” (optional: shown as part of API, or a separate “documentation endpoint”)

- Client → API: HTTPS REST calls
- API → Alpha Vantage: HTTPS requests for FX rates
- Client → Swagger UI: open docs endpoint

**Notes to add**
- Environment variable: `ALPHA_VANTAGE_API_KEY` used by the API when calling Alpha Vantage.

Even though this is a single service repo, you still want to separate “containers” conceptually:

**Containers (inside your system boundary)**
- **NestJS Application (Node.js runtime)**
- REST Controllers
- Services
- DTO validation layer
- Swagger/OpenAPI middleware

**External containers**
- Alpha Vantage API

**Data store**

**Optional “Dev/CI” container**
- “Jest test runner” calling the API in e2e tests (useful for engineering audiences).

This is where you map the repo structure directly.

**Inside “NestJS Application” container**
- `AppModule` (`src/app.module.ts`)
- Wires Controller + Service
- `AppController` (`src/app.controller.ts`)
- Endpoints:
- `GET /fx-rates`
- `POST /top-up/:userId`
- `GET /balance/:userId`
- `POST /fx-conversion`
- `AppService` (`src/app.service.ts`)
- Responsibilities to show as sub-components or bullet notes:
- Fetch live FX rate (Alpha Vantage integration)
- Perform conversion calculation
- Account balance update (top-up, debit)
- Store/retrieve latest rates + user balances (in-memory if applicable)
- DTOs (`src/dto/Account.dto.ts`, `src/dto/FxConversion.dto.ts`)
- Validation boundary (request payload shaping)

**External dependency**
- Alpha Vantage API

- Controller → Service (method calls)
- Service → Alpha Vantage (HTTP)
- Controller ↔ DTOs (validation/serialization)
- Service ↔ Store/DB (read/write)

##### Client sends conversion request (`FxConversion.dto`)
2. Service retrieves rate (from Store or Alpha Vantage), checks balance, debits/credits, persists transaction (if any)

##### Technologies/frameworks to explicitly label
Labels to prevent ambiguity:
- **NestJS** (Controllers/Providers/Modules)
- **Node.js** runtime
- **TypeScript** (build to `dist/`)
- **Swagger/OpenAPI** at `/api` (from `main.ts`)
- **Jest** (unit + e2e)
- **Alpha Vantage** (external HTTP API; requires API key)

- Client(s) → Forex Trading System API → Alpha Vantage
- Swagger UI endpoint shown

- Node/NestJS app container
- In-memory store (or planned DB)
- Alpha Vantage external

- `main.ts` (bootstrap + Swagger + global validation)
- `AppModule` (wiring)
- `AppController` (endpoint list)
- `AppService` (rate fetch, conversion, balances)
- DTOs (validation boundary)
- External Alpha Vantage API

- Client → Controller → Service → (Store + Alpha Vantage) → Service → Controller → Client

This set will be both accurate to the repo and detailed enough for a principal-level architecture review.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 1 — System Context
  %% =========================
  subgraph "Level 1 — System Context"
    direction TB

    Client["API Client(s)\n(Browser/Mobile/Postman/Service)"]:::external
    SwaggerUI["Swagger UI\nGET /api"]:::docs
    System["Forex Trading System API\n(NestJS REST API)"]:::system
    AlphaVantage["Alpha Vantage FX API\n(External)"]:::external

    Client -->|"HTTPS REST"| System
    Client -->|"OpenAPI docs"| SwaggerUI
    SwaggerUI -->|"Served by"| System
    System -->|"HTTPS (uses ALPHA_VANTAGE_API_KEY)"| AlphaVantage
  end

  %% =========================
  %% Level 2 — Containers
  %% =========================
  subgraph "Level 2 — Containers (Runtime View)"
    direction TB

    subgraph "System Boundary: Forex Trading System API"
      direction TB

      NodeRuntime["Node.js Runtime\nTypeScript → dist/"]:::runtime

      subgraph "NestJS Application Container"
        direction TB
        SwaggerMiddleware["Swagger/OpenAPI Middleware\n(/api)"]:::docs
        ValidationLayer["Global Validation/Pipes\n(DTO-boundary)"]:::nest
        RestAPI["REST API (Controllers)"]:::nest
        Services["Application/Domain Services"]:::nest
        InMemStore[("In-memory Store\n(rates/balances/conversions)")]:::store
        FutureDB["Future/Planned DB\n(e.g., Postgres/Redis)\n(Not present in repo)"]:::future
      end

      NodeRuntime -->|"hosts"| RestAPI
      NodeRuntime -->|"hosts"| Services
      NodeRuntime -->|"hosts"| SwaggerMiddleware
      NodeRuntime -->|"applies"| ValidationLayer

      RestAPI -->|"internal calls"| Services
      Services <-->|"read/write"| InMemStore
      Services -.->|"planned persistence"| FutureDB
    end

    AlphaVantage2["Alpha Vantage FX API\n(External)"]:::external
    Services -->|"HTTPS requests"| AlphaVantage2

    JestRunner["Jest Test Runner\n(Unit + E2E)"]:::test
    JestRunner -->|"E2E: spins up & calls"| RestAPI
  end

  %% =========================
  %% Level 3 — Components (Repo Mapping)
  %% =========================
  subgraph "Level 3 — Component Diagram (NestJS Code Structure)"
    direction TB

    Bootstrap["NestJS Bootstrap\n(main.ts)\n- createApp\n- Swagger setup\n- global pipes\n- listen()"]:::nest
    AppModule["AppModule\n(app.module.ts)\n- wires controllers/providers"]:::nest

    AppController["AppController\n(app.controller.ts)\nEndpoints:\n- GET /fx-rates\n- POST /top-up/:userId\n- GET /balance/:userId\n- POST /fx-conversion"]:::api

    AppService["AppService\n(app.service.ts)\nCapabilities:\n- fetch live FX rates\n- perform conversion\n- top-up & balance updates\n- in-memory storage/cache\n- Alpha Vantage integration"]:::service

    DTOAccount["Account DTO\n(dto/Account.dto.ts)\n(validation/schema)"]:::dto
    DTOFxConv["FX Conversion DTO\n(dto/FxConversion.dto.ts)\n(validation/schema)"]:::dto

    AlphaVantage3["Alpha Vantage FX API"]:::external
    Store3[("In-memory Store\n(implicit in service)")]:::store

    Bootstrap -->|"bootstraps"| AppModule
    AppModule -->|"registers"| AppController
    AppModule -->|"provides"| AppService

    AppController -->|"validate/deserialize"| DTOAccount
    AppController -->|"validate/deserialize"| DTOFxConv
    AppController -->|"calls"| AppService

    AppService -->|"HTTPS (API key)"| AlphaVantage3
    AppService <-->|"read/write"| Store3

    subgraph "Testing"
      direction TB
      UnitSpec["Unit Tests\n(app.controller.spec.ts)"]:::test
      E2ESpec["E2E Tests\n(test/app.e2e-spec.ts)"]:::test
      JestE2EConfig["Jest E2E Config\n(test/jest-e2e.json)"]:::test
      UnitSpec -->|"tests"| AppController
      E2ESpec -->|"hits endpoints"| AppController
      JestE2EConfig -->|"configures"| E2ESpec
    end

    subgraph "Build & Artifacts"
      direction TB
      Dist["dist/\n(compiled output)"]:::artifact
      DistDTO["dist/dto/\n(compiled DTOs)"]:::artifact
      ToolingNest["nest-cli.json"]:::config
      ToolingTS1["tsconfig.json"]:::config
      ToolingTS2["tsconfig.build.json"]:::config
      Package["package.json\n(scripts/deps)"]:::config
      SwaggerPDF1["SwaggerUI.pdf"]:::docs
      SwaggerPDF2["SwaggerUI4.pdf"]:::docs

      Package -->|"build scripts"| Dist
      Dist -->|"includes"| DistDTO
      ToolingNest -->|"controls build"| Dist
      ToolingTS1 -->|"ts config"| Dist
      ToolingTS2 -->|"build config"| Dist
    end
  end

  %% =========================
  %% Optional — Key Runtime Flow (Conversion)
  %% =========================
  subgraph "Key Flow — POST /fx-conversion (Summary)"
    direction TB
    FClient["Client"]:::external
    FController["AppController\nPOST /fx-conversion"]:::api
    FService["AppService\nconvert()"]:::service
    FStore[("In-memory Store")]:::store
    FAlpha["Alpha Vantage"]:::external

    FClient -->|"HTTPS POST"| FController
    FController -->|"internal call"| FService
    FService -->|"get rate (cache)"| FStore
    FService -->|"if needed: fetch rate"| FAlpha
    FService -->|"update balances + save conversion"| FStore
    FService -->|"result"| FController
    FController -->|"JSON response"| FClient
  end

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click Bootstrap "https://github.com/deepak-meena-github/forex-trading-system/blob/main/src/main.ts"
  click AppModule "https://github.com/deepak-meena-github/forex-trading-system/blob/main/src/app.module.ts"
  click AppController "https://github.com/deepak-meena-github/forex-trading-system/blob/main/src/app.controller.ts"
  click AppService "https://github.com/deepak-meena-github/forex-trading-system/blob/main/src/app.service.ts"
  click DTOAccount "https://github.com/deepak-meena-github/forex-trading-system/blob/main/src/dto/Account.dto.ts"
  click DTOFxConv "https://github.com/deepak-meena-github/forex-trading-system/blob/main/src/dto/FxConversion.dto.ts"
  click UnitSpec "https://github.com/deepak-meena-github/forex-trading-system/blob/main/src/app.controller.spec.ts"
  click E2ESpec "https://github.com/deepak-meena-github/forex-trading-system/blob/main/test/app.e2e-spec.ts"
  click JestE2EConfig "https://github.com/deepak-meena-github/forex-trading-system/blob/main/test/jest-e2e.json"
  click Dist "https://github.com/deepak-meena-github/forex-trading-system/tree/main/dist/"
  click DistDTO "https://github.com/deepak-meena-github/forex-trading-system/tree/main/dist/dto/"
  click ToolingNest "https://github.com/deepak-meena-github/forex-trading-system/blob/main/nest-cli.json"
  click ToolingTS1 "https://github.com/deepak-meena-github/forex-trading-system/blob/main/tsconfig.json"
  click ToolingTS2 "https://github.com/deepak-meena-github/forex-trading-system/blob/main/tsconfig.build.json"
  click Package "https://github.com/deepak-meena-github/forex-trading-system/blob/main/package.json"
  click SwaggerPDF1 "https://github.com/deepak-meena-github/forex-trading-system/blob/main/SwaggerUI.pdf"
  click SwaggerPDF2 "https://github.com/deepak-meena-github/forex-trading-system/blob/main/SwaggerUI4.pdf"

  %% =========================
  %% Styles
  %% =========================
  classDef system fill:#1f77b4,stroke:#0b2d4d,stroke-width:1.5px,color:#ffffff
  classDef nest fill:#2d8cff,stroke:#0b2d4d,stroke-width:1px,color:#ffffff
  classDef api fill:#1463ff,stroke:#0b2d4d,stroke-width:1px,color:#ffffff
  classDef service fill:#0ea5e9,stroke:#0b2d4d,stroke-width:1px,color:#ffffff
  classDef dto fill:#7c3aed,stroke:#2e1065,stroke-width:1px,color:#ffffff
  classDef store fill:#22c55e,stroke:#14532d,stroke-width:1px,color:#062a12
  classDef future fill:#ffffff,stroke:#22c55e,stroke-width:2px,stroke-dasharray:6 4,color:#14532d
  classDef external fill:#6b7280,stroke:#111827,stroke-width:1px,color:#ffffff
  classDef docs fill:#a855f7,stroke:#3b0764,stroke-width:1px,color:#ffffff
  classDef test fill:#f59e0b,stroke:#7c2d12,stroke-width:1px,color:#1f1300
  classDef artifact fill:#94a3b8,stroke:#334155,stroke-width:1px,color:#0b1220
  classDef config fill:#64748b,stroke:#0f172a,stroke-width:1px,color:#ffffff
  classDef runtime fill:#0b4f6c,stroke:#062a3a,stroke-width:1px,color:#ffffff
```
