# nurekeshka/stock-market-api architecture

> Architecture diagram of the GitHub repository nurekeshka/stock-market-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nurekeshka/stock-market-api
- Repository: https://github.com/nurekeshka/stock-market-api

## Overview

##### Project Type and Purpose
- This is a backend API service (“Stock Market API”) built with NestJS.
- It consumes real-time market data from Finnhub IO via WebSockets and provides REST endpoints for account and transaction management.
- It follows a modular, layered architecture using NestJS modules and several shared libraries.

##### File Structure Analysis
- Top-level folders:
- src/ – application entry point (main.ts) and domain modules (accounts, auth).
- libs/ – reusable NestJS libraries:
– common: error handlers, validation pipes, guards, interceptors
– configuration: centralized config loading (base.json, test.json)
– database: NestJS DatabaseModule with in-memory and (presumably) real DB adapters
– finnhub: connectors/gateway/service for external Finnhub IO integration
- Tests: unit tests located alongside code, end-to-end tests under test/.

##### README Insights
- Describes “Stock Market API” built on NestJS, outlines architecture overview in docs/systems.png.
- Uses JWT auth, Mongoose schemas for accounts, holdings, transactions.
- External dependency: Finnhub IO WebSocket API for live trade data.

##### Main Components
a. API Layer (NestJS App)
- Entry point: src/main.ts → boots AppModule.
- HTTP Server: handles REST controllers (AccountsController, TransactionsController, AuthController).
- WebSocket Gateway: FinnhubGateway listens for market data events and forwards to services.
b. Domain Modules
- AuthModule: JWT strategy, hash strategy, AuthService.
- AccountsModule: AccountsService, HoldingsService, TransactionsService.
c. Shared Libraries (NestJS Modules)
- CommonModule: validation pipes, error handlers, interceptors, guards.
- ConfigurationModule: loads environment/config JSONs.
- DatabaseModule: abstracts DB connectivity (MongoDB via Mongoose or in-memory for tests).
- FinnhubModule: FinnhubConnector (WS client), FinnhubService handles data normalization.
d. Persistence
- MongoDB (or other configured DB) with collections: accounts, holdings, transactions.
e. External Services
- Finnhub IO WebSocket API (live trades).
- (Potential) Third-party REST APIs if needed.
f. Clients
- Frontend or CLI (not shown in repo) consumes public API endpoints.
- E2E tests (test/auth.e2e-spec.ts) as a consumer.

##### Relationships and Interactions
- HTTP client → NestJS HTTP controllers → Domain services → DatabaseModule → MongoDB.
- Finnhub WebSocket → FinnhubConnector → FinnhubGateway events → FinnhubService → downstream modules (e.g., update holdings or broadcast).
- Auth flows: client logs in → AuthController → AuthService (validates, issues JWT) → subsequent requests go through JWT guard in CommonModule.
- ConfigurationModule provides config to all modules via DI (e.g., DB connection URI, Finnhub API key).

##### Architectural Patterns and Principles
- Modular Monorepo: shared libs + domain modules.
- Layered architecture: Controllers → Services → Repositories (DatabaseModule) → External Connectors.
- Dependency Injection (NestJS).
- Single Responsibility: each module/library has clear purpose (config, common utilities, external integration).
- Event-driven stream handling for market data via WebSocket Gateway.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    HTTPClient["HTTP Client"]:::client
    E2ETests["E2E Tests"]:::test
    FinnhubCloud["Finnhub IO WebSocket API"]:::external

    %% Entry Point
    MainTS["main.ts"]:::entry
    MainTS -->|boots| AppModule

    %% Application Boundary
    subgraph "NestJS Application Boundary"
        direction TB
        AppModule["AppModule"]:::core

        %% API Layer
        subgraph "API Layer"
            direction TB
            AccountsController["AccountsController"]:::controller
            TransactionsController["TransactionsController"]:::controller
            AuthController["AuthController"]:::controller
            FinnhubGateway["Finnhub WebSocket Gateway"]:::gateway
        end

        %% Domain Modules
        subgraph "Domain Modules"
            direction TB
            subgraph "Auth Module"
                direction TB
                AuthService["AuthService"]:::service
                JWTStrategy["JWT Strategy"]:::strategy
                HashStrategy["Hash Strategy"]:::strategy
            end
            subgraph "Accounts Module"
                direction TB
                AccountsService["AccountsService"]:::service
                HoldingsService["HoldingsService"]:::service
                TransactionsService["TransactionsService"]:::service
                AccountsSchema["accounts.schema.ts"]:::schema
                HoldingsSchema["holdings.schema.ts"]:::schema
                TransactionsSchema["transactions.schema.ts"]:::schema
            end
        end

        %% Shared Libraries
        subgraph "Shared Modules"
            direction TB
            CommonModule["CommonModule"]:::shared
            ConfigurationModule["ConfigurationModule"]:::shared
            DatabaseModule["DatabaseModule"]:::shared
            FinnhubModule["FinnhubModule"]:::shared
        end

        %% Persistence
        MongoDB["MongoDB\n(accounts, holdings, transactions)"]:::db
    end

    %% Relationships
    HTTPClient -->|HTTP/HTTPS| AccountsController
    HTTPClient -->|HTTP/HTTPS| TransactionsController
    HTTPClient -->|HTTP/HTTPS| AuthController
    E2ETests -->|HTTP/HTTPS| AuthController

    AccountsController -->|"calls"| AccountsService
    TransactionsController -->|"calls"| TransactionsService
    AuthController -->|"calls"| AuthService

    AccountsService -->|DB ops| DatabaseModule
    HoldingsService -->|DB ops| DatabaseModule
    TransactionsService -->|DB ops| DatabaseModule
    DatabaseModule -->|connects| MongoDB

    FinnhubCloud -->|WS/WSS| FinnhubConnector
    FinnhubConnector -->|"emits events"| FinnhubGateway
    FinnhubGateway -->|"forwards data"| FinnhubService
    FinnhubService -->|"updates holdings"| HoldingsService

    %% Module wiring
    AppModule --> AccountsModule
    AppModule --> AuthModule
    AppModule --> FinnhubModule
    AppModule --> CommonModule
    AppModule --> ConfigurationModule
    AppModule --> DatabaseModule
    AppModule --> AccountsController
    AppModule --> TransactionsController
    AppModule --> AuthController
    AppModule --> FinnhubGateway

    %% Config injection (dotted)
    ConfigurationModule -.->|provides config| AppModule
    ConfigurationModule -.->|provides config| DatabaseModule
    ConfigurationModule -.->|provides config| FinnhubModule
    ConfigurationModule -.->|provides config| CommonModule

    %% Click Events
    click MainTS "https://github.com/nurekeshka/stock-market-api/blob/main/src/main.ts"
    click AppModule "https://github.com/nurekeshka/stock-market-api/blob/main/src/app.module.ts"
    click AccountsController "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/controller/holdings.controller.ts"
    click TransactionsController "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/controller/transactions.controller.ts"
    click AuthController "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/auth/controller/auth.controller.ts"
    click FinnhubGateway "https://github.com/nurekeshka/stock-market-api/blob/main/libs/finnhub/src/gateway/finnhub.gateway.ts"
    click FinnhubConnector "https://github.com/nurekeshka/stock-market-api/blob/main/libs/finnhub/src/gateway/finnhub.connector.ts"
    click FinnhubService "https://github.com/nurekeshka/stock-market-api/blob/main/libs/finnhub/src/service/finnhub.service.ts"
    click FinnhubModule "https://github.com/nurekeshka/stock-market-api/blob/main/libs/finnhub/src/finnhub.module.ts"
    click AuthModule "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/auth/auth.module.ts"
    click AuthService "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/auth/service/auth.service.ts"
    click JWTStrategy "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/auth/strategies/jwt.strategy.ts"
    click HashStrategy "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/auth/strategies/hash.strategy.ts"
    click AccountsModule "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/accounts.module.ts"
    click AccountsService "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/service/accounts.service.ts"
    click HoldingsService "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/service/holdings.service.ts"
    click TransactionsService "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/service/transactions.service.ts"
    click AccountsSchema "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/schemas/accounts.schema.ts"
    click HoldingsSchema "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/schemas/holdings.schema.ts"
    click TransactionsSchema "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/schemas/transactions.schema.ts"
    click CommonModule "https://github.com/nurekeshka/stock-market-api/blob/main/libs/common/src/index.ts"
    click ConfigurationModule "https://github.com/nurekeshka/stock-market-api/blob/main/libs/configuration/src/configuration.module.ts"
    click DatabaseModule "https://github.com/nurekeshka/stock-market-api/blob/main/libs/database/src/database.module.ts"
    click E2ETests "https://github.com/nurekeshka/stock-market-api/blob/main/test/auth.e2e-spec.ts"
    click FinnhubService.spec "https://github.com/nurekeshka/stock-market-api/blob/main/libs/finnhub/src/service/finnhub.service.spec.ts"
    click DatabaseModule.spec "https://github.com/nurekeshka/stock-market-api/blob/main/libs/database/src/database.module.spec.ts"
    click ConfigurationModule.spec "https://github.com/nurekeshka/stock-market-api/blob/main/libs/configuration/src/configuration.module.spec.ts"
    click commonServiceSpec "https://github.com/nurekeshka/stock-market-api/blob/main/libs/common/src/common.service.spec.ts"
    click AccountsService.spec "https://github.com/nurekeshka/stock-market-api/blob/main/src/modules/accounts/service/accounts.service.spec.ts"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef entry fill:#fff,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
    classDef core fill:#bbf,stroke:#333,stroke-width:2px
    classDef controller fill:#fd7e14,stroke:#333,stroke-width:1px
    classDef gateway fill:#20c997,stroke:#333,stroke-width:1px
    classDef service fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef strategy fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef schema fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef shared fill:#20B2AA,stroke:#333,stroke-width:1px
    classDef db fill:#C0C0C0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef external fill:#add8e6,stroke:#333,stroke-width:1px
    classDef test fill:#ffe4e1,stroke:#333,stroke-width:1px
```
