How spoutchainlink/rwa-deploy-backend works
Project Type and Purpose
• Type: Backend API service (NestJS)
• Purpose: Bridge between traditional finance (Alpaca Markets) and Web3 smart-contract trading, with persistent storage (Supabase) and real-time event listening.
Main Components
A. External Systems
• Client / API consumer (e.g., frontend or third-party)
• Alpaca Markets API (market data)
• Ethereum Blockchain network (RPC HTTP & WSS endpoints)
B. API Gateway & HTTP Layer
• NestJS (main.ts, app.module.ts)
• API-key middleware (shared/middleware/api-key.middleware.ts)
C. NestJS Modules (logical service boundaries)
1. Orders Module
– Controller (orders.controller.ts)
– Service (orders.service.ts)
2. Reserves Module
– Controller (reserves.controller.ts)
– Service (reserves.service.ts)
3. Alpaca Module
– Controller (alpaca.controller.ts)
– Service (alpaca.service.ts)
4. Web3 Module
– Provider Factory (provider.factory.ts)
– EventListener Service (event-listener.service.ts)
– Token Service (token.service.ts)
5. Supabase Module
– Service (supabase.service.ts)
6. Shared Module
– Models / DTOs
– ABI artifacts
– Middleware
D. Data Storage
• Supabase (PostgreSQL)
E. Event & Message Flows
• Outbound HTTP requests to Alpaca (via Axios inside alpaca.service)
• Outbound JSON-RPC/WebSocket to Ethereum (via ethers.js in web3)
• Internal events: e.g., order placement → token mint/burn → reserve updates
F. Security & Config
• API-key middleware (shared)
• Env-driven config for RPC endpoints, API keys, Supabase key
Relationships & Data Flows
• Client → (x-api-key) → NestJS HTTP Server
• HTTP Layer → corresponding Controller
• Controller → Service
• Service may:
• Query/update Supabase
• Call Alpaca API
• Call Web3 provider (send/receive transactions)
• Web3 EventListener → processes on-chain events → updates Supabase / notifies internal modules
• Reserves Module reads/writes reserve balances in Supabase
• Orders Module orchestrates buys/sells across Web3 + Supabase
Architectural Patterns & Principles
• Modular Monolith (NestJS modules segregate features)
• Dependency Injection (services injected into controllers)
• Single Responsibility (each module handles one domain)
• Event-driven updates (blockchain events trigger internal flows)
• External Integration Adapters (Alpaca & Web3 providers)
Elements
• Clear labels (module names, controller vs. service)
• Middleware layer explicitly drawn between client and controllers
• Notes on event-driven flows (blockchain → EventListener → Supabase)