# harshul786/trading-signals architecture

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

- Interactive diagram: https://gitdiagram.com/harshul786/trading-signals
- Repository: https://github.com/harshul786/trading-signals

## Overview

##### Project type and purpose
- This is a Node.js/Express backend service for a cryptocurrency trading platform.
- Purpose: expose RESTful endpoints for user authentication, trade management, trade‐plan management, real‐time notifications (via Telegram), and portfolio tracking.
- Future plan: add a user‐facing frontend that consumes these APIs.

##### File structure
- Top‐level files: index.js (app entry), package.json (dependencies), vercel.json (deployment), README.md, .env (config).
- src/main
- api/ – route handlers (userResource, tradeResource, tradePlanResource).
- config/ – database configuration (mongoose.js).
- middleware/ – JWT authentication (auth.js).
- model/ – Mongoose schemas (user.js, trade.js, tradePlan.js).
- utils/ – algorithmic helpers (supertrend.js, tradeUtils.js), Telegram integration (telegram.js), OHLCV data utilities.
- src/tests – historical signal‐strategy tests against SOL‐USDC pairs over various timeframes.
- Indicates an MVC‐inspired pattern: routes → controllers/resources → service/utils → data (Mongo models).

##### README insights
- Describes core features and intended future UI.
- Lists environment variables for MongoDB, JWT, Telegram, client CORS and port.
- Deployment target: Vercel (serverless Node).

##### Main components & interactions
a. Clients
- (Future) Web/mobile UI or API clients
- External schedulers or bots for running tests
b. API Layer (Express.js)
- userResource
- tradeResource
- tradePlanResource
- auth middleware for JWT validation
c. Business Logic / Utilities
- supertrend calculation
- tradeUtils (position sizing, risk management)
- telegram.js (push notifications)
- ohlcv.js (historical data parsing for tests)
d. Data Layer
- MongoDB database
- Mongoose ORM models: User, Trade, TradePlan
e. External services
- Telegram Bot API
- (Potential) Crypto exchange APIs for price data (implied via tests)
f. Deployment
- Vercel serverless functions hosting index.js

##### Architectural patterns & design principles
- Layered (API → Middleware → Services/Utils → Data)
- Separation of concerns: authentication abstracted into middleware, business logic in utils.
- Stateless RESTful services using JWT.
- Modular, test‐driven approach: isolate strategy tests under src/tests.

##### Detail level
- Middleware chain and model relationships.
- Don’t overcomplicate—focus on primary flows: user auth, trade management, notifications, and data persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        direction TB
        Client["API Clients\n(Web/Mobile/CLI)"]:::client
    end

    %% API Gateway / Entry
    subgraph "API Layer (Express on Vercel)"
        direction TB
        APIGateway["API Gateway\n(index.js)"]:::api
        APIGateway -->|HTTP request| AuthMiddleware
        APIGateway -->|Init DB connection| DBConfig
    end

    %% Middleware & Config
    AuthMiddleware["Auth Middleware\n(auth.js)"]:::api
    DBConfig["DB Config\n(mongoose.js)"]:::config

    %% Route Handlers
    subgraph "Route Handlers" 
        direction TB
        UserRH["User Resource\n(userResource.js)"]:::api
        TradeRH["Trade Resource\n(tradeResource.js)"]:::api
        PlanRH["Trade-Plan Resource\n(tradePlanResource.js)"]:::api
    end
    AuthMiddleware --> UserRH
    AuthMiddleware --> TradeRH
    AuthMiddleware --> PlanRH

    %% Business Logic / Utilities
    subgraph "Business Logic / Utilities"
        direction TB
        Supertrend["Supertrend Algorithm\n(supertrend.js)"]:::service
        TradeUtils["Trade Utilities\n(tradeUtils.js)"]:::service
        TelegramUtil["Telegram Integration\n(telegram.js)"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MongoDB[(MongoDB)]:::database
        UserModel["User Model\n(user.js)"]:::model
        TradeModel["Trade Model\n(trade.js)"]:::model
        PlanModel["TradePlan Model\n(tradePlan.js)"]:::model
    end
    DBConfig --> MongoDB
    UserModel --> MongoDB
    TradeModel --> MongoDB
    PlanModel --> MongoDB

    %% Handler to Logic & Data flows
    UserRH -->|CRUD| UserModel
    TradeRH -->|CRUD| TradeModel
    PlanRH -->|CRUD| PlanModel

    TradeRH -->|"calc signals"| Supertrend
    TradeRH -->|"position sizing"| TradeUtils
    PlanRH -->|"risk mgmt"| TradeUtils

    TradeRH -->|notify| TelegramUtil
    TelegramUtil -->|API call| TelegramAPI

    %% External Services
    subgraph "External Services"
        direction TB
        TelegramAPI["Telegram Bot API"]:::external
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        TestRunner["Test Runner\n(tests.js)"]:::test
        HistoricalTests["Historical Tests\n(src/tests/SOL-USDC/*.txt)"]:::test
    end
    TestRunner -->|reads| HistoricalTests
    TestRunner -->|executes| Supertrend
    TestRunner -->|executes| TradeUtils

    %% Deployment Config
    subgraph "Deployment Configuration"
        direction TB
        VercelConfig["vercel.json"]:::config
        PackageJSON["package.json\npackage-lock.json"]:::config
        Gitignore[".gitignore"]:::config
        Readme["README.md"]:::config
    end
    APIGateway -->|deployed via| VercelConfig

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Rectangle: Components"]:::legend
        L2["Cylinder: Database"]:::legend
        L3["Cloud: External Service"]:::legend
        L4["Colors by layer"]:::legend
    end

    %% Click Events
    click APIGateway "https://github.com/harshul786/trading-signals/blob/main/index.js"
    click UserRH "https://github.com/harshul786/trading-signals/blob/main/src/main/api/userResource.js"
    click TradeRH "https://github.com/harshul786/trading-signals/blob/main/src/main/api/tradeResource.js"
    click PlanRH "https://github.com/harshul786/trading-signals/blob/main/src/main/api/tradePlanResource.js"
    click AuthMiddleware "https://github.com/harshul786/trading-signals/blob/main/src/main/middleware/auth.js"
    click DBConfig "https://github.com/harshul786/trading-signals/blob/main/src/main/config/mongoose.js"
    click UserModel "https://github.com/harshul786/trading-signals/blob/main/src/main/model/user.js"
    click TradeModel "https://github.com/harshul786/trading-signals/blob/main/src/main/model/trade.js"
    click PlanModel "https://github.com/harshul786/trading-signals/blob/main/src/main/model/tradePlan.js"
    click Supertrend "https://github.com/harshul786/trading-signals/blob/main/src/main/utils/supertrend.js"
    click TradeUtils "https://github.com/harshul786/trading-signals/blob/main/src/main/utils/tradeUtils.js"
    click TelegramUtil "https://github.com/harshul786/trading-signals/blob/main/src/main/utils/telegram.js"
    click TestRunner "https://github.com/harshul786/trading-signals/blob/main/src/tests/tests.js"
    click HistoricalTests "https://github.com/harshul786/trading-signals/blob/main/src/tests/SOL-USDC/*.txt"
    click VercelConfig "https://github.com/harshul786/trading-signals/blob/main/vercel.json"
    click PackageJSON "https://github.com/harshul786/trading-signals/blob/main/package.json"
    click Gitignore "https://github.com/harshul786/trading-signals/blob/main/.gitignore"
    click Readme "https://github.com/harshul786/trading-signals/blob/main/README.md"

    %% Styles
    classDef client fill:#D0E6A5,stroke:#333,stroke-width:1px
    classDef api fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef service fill:#C3F7A2,stroke:#333,stroke-width:1px
    classDef model fill:#FCE38A,stroke:#333,stroke-width:1px
    classDef database fill:#F9AFAE,stroke:#333,stroke-width:1px
    classDef external fill:#F5D0A9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef test fill:#E0E0E0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef config fill:#D3D3F3,stroke:#333,stroke-width:1px
    classDef legend fill:#FFFFFF,stroke:#000,stroke-width:0px, font-style:italic
```
