# spoutchainlink/rwa-deploy-backend architecture

> Architecture diagram of the GitHub repository spoutchainlink/rwa-deploy-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spoutchainlink/rwa-deploy-backend
- Repository: https://github.com/spoutchainlink/rwa-deploy-backend

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["Client / API Consumer"]:::external
    Client -->|x-api-key| Middleware["API Key Middleware"]:::middleware
    click Middleware "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/middleware/api-key.middleware.ts"

    %% Backend Boundary
    subgraph "Backend"
        direction TB

        %% Core Init
        Main["main.ts"]:::core
        AppModule["app.module.ts"]:::core
        AppController["app.controller.ts"]:::controller

        click Main "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/main.ts"
        click AppModule "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/app.module.ts"
        click AppController "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/app.controller.ts"

        %% Controllers Layer
        subgraph "Controllers"
            direction TB
            OrdersController["OrdersController"]:::controller
            ReservesController["ReservesController"]:::controller
            AlpacaController["AlpacaController"]:::controller
        end

        click OrdersController "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/orders/orders.controller.ts"
        click ReservesController "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/reserves/reserves.controller.ts"
        click AlpacaController "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/alpaca/alpaca.controller.ts"

        %% Services Layer
        subgraph "Services"
            direction TB
            OrdersService["OrdersService"]:::service
            ReservesService["ReservesService"]:::service
            AlpacaService["AlpacaService"]:::service
            ProviderFactory["ProviderFactory"]:::service
            EventListenerService["EventListenerService"]:::service
            TokenService["TokenService"]:::service
            SupabaseService["SupabaseService"]:::service
        end

        click OrdersService "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/orders/orders.service.ts"
        click ReservesService "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/reserves/reserves.service.ts"
        click AlpacaService "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/alpaca/alpaca.service.ts"
        click ProviderFactory "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/web3/providers/provider.factory.ts"
        click EventListenerService "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/web3/services/event-listener.service.ts"
        click TokenService "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/web3/services/token.service.ts"
        click SupabaseService "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/supabase/supabase.service.ts"

        %% Shared Utilities
        subgraph "Shared Module"
            direction TB
            ABIs["ABI Artifacts"]:::shared
            Models["DTO / Models"]:::shared
        end

        click ABIs "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/abi/ERC3643.abi.ts"
        click ABIs "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/abi/IDENTITY_REGISTRY.abi.ts"
        click ABIs "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/abi/ORDER_EVENTS.abi.ts"
        click Models "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/models/issue-kyc-signature.dto.ts"
        click Models "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/models/kyc-signature-response.model.ts"
        click Models "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/models/order-request.model.ts"
        click Models "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/models/order-response.model.ts"
        click Models "https://github.com/spoutchainlink/rwa-deploy-backend/blob/main/src/shared/models/reserve-response.model.ts"
    end

    %% External Services and DB
    AlpacaAPI["Alpaca Markets API"]:::external
    EthereumRPC["Ethereum RPC (HTTP)"]:::external
    EthereumWS["Ethereum RPC (WSS)"]:::external
    SupabaseDB["Supabase (PostgreSQL)"]:::db

    %% Flows
    Middleware --> Main
    Main --> AppModule
    AppModule --> AppController

    AppController --> OrdersController
    AppController --> ReservesController
    AppController --> AlpacaController

    OrdersController --> OrdersService
    ReservesController --> ReservesService
    AlpacaController --> AlpacaService

    OrdersService -->|SQL| SupabaseService
    OrdersService -->|REST| AlpacaService
    OrdersService -->|invoke| TokenService

    ReservesService -->|SQL| SupabaseService

    AlpacaService -->|REST| AlpacaAPI
    TokenService -->|JSON-RPC| EthereumRPC

    EventListenerService -->|WebSocket| EthereumWS
    EventListenerService -.->|process events| SupabaseService

    SupabaseService -->|SQL| SupabaseDB

    %% Utilization of Shared
    OrdersService --> ABIs
    OrdersService --> Models
    ReservesService --> Models
    AlpacaService --> Models
    TokenService --> ABIs

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef middleware fill:#faa,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef controller fill:#bbe,stroke:#333,stroke-width:1px
    classDef service fill:#ddf,stroke:#333,stroke-width:1px
    classDef shared fill:#efe,stroke:#333,stroke-width:1px
    classDef db fill:#bfb,stroke:#333,stroke-width:1px
```
