# raghavmaheshwari2024/blockchain_server architecture

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

- Interactive diagram: https://gitdiagram.com/raghavmaheshwari2024/blockchain_server
- Repository: https://github.com/raghavmaheshwari2024/blockchain_server

## Overview

##### What this project is (type + purpose)
This is a **backend-only Node.js/Express service** that:
- exposes an HTTP API to **register wallets** (`/api/wallet/register`)
- kicks off **synchronization jobs** that pull **on-chain transaction history** from an external provider (**Goldrush API**)
- persists normalized results into **MongoDB** via **Mongoose** (`wallet` + `ledgerEntry` collections)

So the “system” is essentially: **Client → Express API → Sync Orchestrator → Goldrush API → MongoDB**, with background/job-style execution for historical and live syncing.

##### Runtime/Bootstrap Layer
- `src/index.js`
- Express app initialization
- dotenv/env loading
- MongoDB connection
- route mounting

##### Configuration Layer
- `src/config/env.js` – environment variable access/validation
- `src/config/mongo.js` – MongoDB connection logic

##### HTTP Interface Layer (Transport)
- `src/routes/wallet.routes.js` – defines endpoints
- `src/controllers/wallet.controller.js` – request handling, calls services

##### Domain/Data Layer (Persistence)
- `src/models/wallet.model.js`
- `src/models/ledgerEntry.model.js`

##### Application/Orchestration Services
- `src/services/ledger.service.js` – historical sync orchestration (core business flow)
- `src/services/goldrush.service.js` – Goldrush API client (external integration)
- `src/services/python.service.js` – integration point to a Python process/service (callout as “optional sidecar/external compute”)

##### Background/Job Execution
- `src/jobs/historicalSync.job.js`
- `src/jobs/liveSync.job.js`

- Historical sync (batch/backfill)
- Live sync (polling/subscription style)

- triggered by controller on registration (historical)
- scheduled/continuous loop (live)

##### Cross-cutting Utilities (show as shared components)
- `src/utils/logger.js`
- `src/utils/retry.js` (exponential backoff)
- `src/utils/rateLimiter.js` (in-process rate limiting)

##### API Clients
- curl / Postman / frontend / other backend
##### Node Wallet Sync Server (Express)
- Routes
- Controllers
- Services
- Jobs
- Utilities
##### MongoDB
- wallets collection
- ledger_entries (or ledgerEntry) collection
##### External Services
- Goldrush API (primary)
- Tatum API (secondary/optional)
##### Optional: Python Integration
- Python script/process or separate Python microservice (since there is `python.service.js`)

##### Client → Express API
- `POST /api/wallet/register { address, chain }`
##### Route → Controller
- `wallet.routes.js` → `wallet.controller.js`
##### Controller → Wallet Model (MongoDB)
- create/find wallet document
##### Controller → Ledger Sync Orchestrator
- call into `ledger.service.js` to start historical sync
##### Ledger Service → Goldrush Service
- HTTP calls (Axios) with bearer token
##### Goldrush Service → Goldrush API
- `GET transactions(...)` (paged)
##### Ledger Service → LedgerEntry Model (MongoDB)
- upsert/insert normalized ledger entries
##### Ledger Service → Logger
- log progress/errors
##### Goldrush Service → Retry + RateLimiter
- wrap outbound calls with backoff + throttling

This as two phases:
- **Phase A (request path)**: client→API→DB (wallet created) → “enqueue/start sync”
- **Phase B (background path)**: sync job/service → external API → DB

##### Historical vs Live sync
- **Historical Sync Job**: backfills until “oldest tx” reached
- **Live Sync Job**: periodically fetches latest txs (polling) or keeps cursor

If the actual implementation is “in-process jobs”, show them inside the Node server boundary with a note: “Runs in same process (no external queue)”.

This repo strongly implies a classic layered approach:

- **Transport Layer**: Express routes/controllers
- **Application Services**: ledger sync orchestration
- **Integration Adapters**: `goldrush.service.js`, `tatum.service.js`, `python.service.js`
- **Persistence Layer**: Mongoose models + MongoDB
- **Cross-cutting concerns**: logging, retries, rate limiting

##### What to label explicitly (technologies + boundaries)
- **Node.js (ES Modules)** + **Express**
- **MongoDB** + **Mongoose**
- **Axios**
- **Goldrush API (Bearer token: `GOLDRUSH_API_KEY`)**
- **Environment variables** (`MONGO_URI`, `PORT`, `GOLDRUSH_API_KEY`)
- **In-process rate limiter** (important constraint: scaling implications)
- **Retry w/ exponential backoff** (resilience behavior)

Trust boundaries:
- “Internal network” vs “External (Goldrush/Tatum)”
- “Data store boundary” (MongoDB)

- **Rectangles**: internal modules (controllers/services/jobs/models)
- **Cloud**: external APIs (Goldrush/Tatum)

- `HTTP POST /api/wallet/register`
- `HTTPS GET /transactions (paged)`
- `MongoDB insert/upsert ledger entries`

- Blue: HTTP/API layer
- Purple: services/orchestration
- Green: persistence
- Orange: external dependencies
- Gray: cross-cutting utilities

##### Project-specific “don’t miss this” details to capture
To be maximally accurate for this repo, explicitly include:
- **Historical sync starts immediately after wallet registration** (as per README: “Wallet registered. Sync started.”)
- **Failure handling**: “errors logged, server keeps running” (put note near retry/logger)
- **In-process controls**: rate limiter is not distributed—call out that horizontal scaling would need coordination or external rate limiting.
- **Two sync modes**: historical + live jobs exist in `src/jobs/` even if only historical is described in README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram 1 — System/Container Context (C4 L2)
    %% =========================
    subgraph C1["Diagram 1: System Context (C4 L2)"]
        direction TB

        Client["API Clients\n(curl/Postman/Frontend/Other backend)"]:::external

        subgraph ServerCtx["Node Wallet Sync Server\n(Node.js ES Modules + Express)"]
            direction TB
            APICtx["HTTP API\nPOST /api/wallet/register\n{ address, chain }"]:::api
            JobsCtx["In-process Job Runner / Scheduler\n(no external queue)"]:::job
            SyncCtx["Sync Orchestrator\n(Ledger Sync Service)"]:::service
        end

        Mongo["MongoDB\n(Mongoose)\n- wallets\n- ledgerEntries"]:::db

        subgraph ExternalNet["External (Untrusted Network)"]
            direction TB
            Goldrush["Goldrush API\n(Bearer token: GOLDRUSH_API_KEY)"]:::externalApi
            Tatum["Tatum API (optional)"]:::externalApiOpt
            Python["Python runtime/service (optional)\nIPC/HTTP/child_process (impl-dependent)"]:::externalApiOpt
        end

        EnvVars["Environment Variables\nPORT, MONGO_URI, GOLDRUSH_API_KEY"]:::config

        %% Context connections (vertical)
        Client -->|"HTTP/JSON"| APICtx
        EnvVars -->|"configures"| ServerCtx

        APICtx -->|"create/find wallet"| Mongo
        APICtx -->|"kickoff historical sync"| SyncCtx

        JobsCtx -->|"historical/backfill"| SyncCtx
        JobsCtx -->|"live polling/subscription"| SyncCtx

        SyncCtx -->|"MongoDB insert/upsert normalized ledger entries"| Mongo
        SyncCtx -->|"HTTPS (Axios) GET /transactions (paged)"| Goldrush
        SyncCtx -.->|"HTTPS (Axios) alt provider"| Tatum
        SyncCtx -.->|"IPC/HTTP compute/enrichment"| Python
    end

    %% =========================
    %% Diagram 2 — Component Diagram inside Node server (C4 L3)
    %% =========================
    subgraph C2["Diagram 2: Component Diagram (C4 L3) — Inside Node Wallet Sync Server"]
        direction TB

        %% --- Bootstrap / Config ---
        subgraph Boot["Runtime/Bootstrap Layer"]
            direction TB
            Index["Bootstrap + Express App\n(load dotenv, mount routes)"]:::runtime
        end

        subgraph Config["Configuration Layer"]
            direction TB
            Env["env.js\n(env vars access/validation)"]:::config
            MongoConn["mongo.js\n(MongoDB connection logic)"]:::config
        end

        %% --- Transport ---
        subgraph Transport["HTTP Interface Layer (Transport)"]
            direction TB
            Routes["wallet.routes.js\nREST Routes\nPOST /api/wallet/register"]:::api
            Controller["wallet.controller.js\nWallet Controller"]:::controller
        end

        %% --- Application / Orchestration ---
        subgraph App["Application/Orchestration Services"]
            direction TB
            LedgerSvc["ledger.service.js\nLedger Sync Orchestrator\n(historical sync core flow)"]:::service

            subgraph Adapters["Integration Adapters (External Providers)"]
                direction TB
                GoldrushSvc["goldrush.service.js\nGoldrush API Client\n(Axios + bearer token)"]:::adapter
                TatumSvc["tatum.service.js\nTatum API Client (optional)"]:::adapterOpt
                PythonSvc["python.service.js\nPython Integration Adapter (optional)"]:::adapterOpt
            end
        end

        %% --- Background Jobs ---
        subgraph Jobs["Background/Job Execution (in-process)"]
            direction TB
            HistJob["historicalSync.job.js\nHistorical Sync Job\n(backfill until oldest tx)"]:::job
            LiveJob["liveSync.job.js\nLive Sync Job\n(poll latest txs / keep cursor)"]:::job
            JobsNote["Note: Runs in same process\n(no external queue)"]:::note
        end

        %% --- Persistence ---
        subgraph Persist["Domain/Data Layer (Persistence)"]
            direction TB
            WalletModel["wallet.model.js\nWallet Model (Mongoose)"]:::model
            LedgerModel["ledgerEntry.model.js\nLedgerEntry Model (Mongoose)"]:::model
            Mongo2["MongoDB\n- wallets\n- ledgerEntries"]:::db
        end

        %% --- Utilities ---
        subgraph Utils["Cross-cutting Utilities (shared)"]
            direction TB
            Logger["logger.js\nLogger"]:::util
            Retry["retry.js\nRetry (exp backoff)"]:::util
            RateLimiter["rateLimiter.js\nIn-process rate limiter\n(not distributed)"]:::util
            UtilNote["Failure handling:\nerrors logged, server keeps running"]:::note
        end

        %% --- External systems (for component-level calls) ---
        subgraph TrustBoundary["External (Untrusted Network)"]
            direction TB
            GoldrushAPI2["Goldrush API\nGET /transactions (paged)"]:::externalApi
            TatumAPI2["Tatum API (optional)"]:::externalApiOpt
            PythonExt2["Python runtime/service (optional)"]:::externalApiOpt
        end

        %% --- Wiring / flows (keep vertical) ---
        Index -->|"loads"| Env
        Index -->|"connects (MONGO_URI)"| MongoConn
        MongoConn -->|"opens connection"| Mongo2
        Index -->|"mounts /api/wallet"| Routes

        Routes -->|"calls handler"| Controller

        %% Registration request path (Phase A)
        Controller -->|"create/find wallet doc"| WalletModel
        WalletModel -->|"Mongoose write/read"| Mongo2

        Controller -->|"start historical sync immediately\n('Wallet registered. Sync started.') "| LedgerSvc

        %% Background jobs (Phase B)
        HistJob -->|"triggers backfill"| LedgerSvc
        LiveJob -->|"triggers periodic sync"| LedgerSvc
        JobsNote --- HistJob
        JobsNote --- LiveJob

        %% Orchestrator to persistence
        LedgerSvc -->|"normalize + upsert ledger entries"| LedgerModel
        LedgerModel -->|"Mongoose insert/upsert"| Mongo2

        %% Orchestrator to adapters
        LedgerSvc -->|"fetch tx history"| GoldrushSvc
        LedgerSvc -.->|"alt provider"| TatumSvc
        LedgerSvc -.->|"optional compute"| PythonSvc

        %% Adapter cross-cutting concerns
        GoldrushSvc -->|"throttle outbound calls"| RateLimiter
        GoldrushSvc -->|"wrap calls"| Retry
        GoldrushSvc -->|"log progress/errors"| Logger

        Retry -->|"log retry/failures"| Logger
        RateLimiter -->|"log throttling"| Logger
        UtilNote --- Logger

        %% Adapter to external systems
        GoldrushSvc -->|"HTTPS (Axios)\nBearer GOLDRUSH_API_KEY"| GoldrushAPI2
        TatumSvc -.->|"HTTPS (Axios)"| TatumAPI2
        PythonSvc -.->|"IPC/HTTP/child_process\n(impl-dependent)"| PythonExt2
    end

    %% =========================
    %% Click events (from component_mapping)
    %% =========================
    click Index "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/index.js"
    click Env "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/config/env.js"
    click MongoConn "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/config/mongo.js"
    click Routes "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/routes/wallet.routes.js"
    click Controller "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/controllers/wallet.controller.js"
    click WalletModel "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/models/wallet.model.js"
    click LedgerModel "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/models/ledgerEntry.model.js"
    click LedgerSvc "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/services/ledger.service.js"
    click GoldrushSvc "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/services/goldrush.service.js"
    click TatumSvc "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/services/tatum.service.js"
    click PythonSvc "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/services/python.service.js"
    click HistJob "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/jobs/historicalSync.job.js"
    click LiveJob "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/jobs/liveSync.job.js"
    click Logger "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/utils/logger.js"
    click Retry "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/utils/retry.js"
    click RateLimiter "https://github.com/raghavmaheshwari2024/blockchain_server/blob/main/src/utils/rateLimiter.js"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#E6F4FF,stroke:#1D4ED8,stroke-width:1px,color:#0B1B3A
    classDef api fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1B3A
    classDef controller fill:#BFDBFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1B3A
    classDef service fill:#E9D5FF,stroke:#7C3AED,stroke-width:1px,color:#1F103A
    classDef adapter fill:#F3E8FF,stroke:#7C3AED,stroke-width:1px,color:#1F103A
    classDef adapterOpt fill:#F3E8FF,stroke:#7C3AED,stroke-dasharray: 4 3,stroke-width:1px,color:#1F103A
    classDef job fill:#FFE4CC,stroke:#C2410C,stroke-width:1px,color:#3A1A00
    classDef model fill:#D1FAE5,stroke:#047857,stroke-width:1px,color:#06251C
    classDef db fill:#BBF7D0,stroke:#047857,stroke-width:1px,color:#06251C
    classDef util fill:#E5E7EB,stroke:#374151,stroke-width:1px,color:#111827
    classDef config fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#2A1A00
    classDef runtime fill:#C7D2FE,stroke:#4338CA,stroke-width:1px,color:#0F172A
    classDef externalApi fill:#FFD7D7,stroke:#B91C1C,stroke-width:1px,color:#3A0B0B
    classDef externalApiOpt fill:#FFD7D7,stroke:#B91C1C,stroke-dasharray: 4 3,stroke-width:1px,color:#3A0B0B
    classDef note fill:#F9FAFB,stroke:#9CA3AF,stroke-dasharray: 3 3,stroke-width:1px,color:#111827
```
