How raghavmaheshwari2024/blockchain_server works
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.