# emmanuelist/crossflow architecture

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

- Interactive diagram: https://gitdiagram.com/emmanuelist/crossflow
- Repository: https://github.com/emmanuelist/crossflow

## Overview

##### Main Components
- Backend Services:
- Bridge Service: Orchestrates the cross-chain transfer operations.
- Rate Service: Handles retrieval of exchange rates for African currencies.
- Blockchain Services: Separate modules for Ethereum and Stellar operations (found in both backend/src/services and the dedicated blockchain directories).
- USSD Service: Manages mobile money integration via Africa's Talking.
- Controllers, Routes, and Models: Organized in an MVC-like structure with directories for controllers (handling API endpoints), models (database schema for transactions/users), and routes (HTTP endpoints for Ethereum, Stellar, and rates).
- Configuration and Utilities: Directory for DB and blockchain configuration, error handling, fee calculation, transaction monitoring, and input validation.

- Frontend Components:
- Wallet Dashboard: Manages user wallet and network selection.
- Bridge Interface: UI for initiating transfers.
- Transaction Monitor: Provides real-time transaction status updates.
- Payment Forms: UI forms for deposits and withdrawals handling different payment methods.
- Supporting Libraries & Components: Next.js pages, reusable UI components (buttons, alerts, dialogs, etc.), and hooks (e.g., for wallet interactions).

- Blockchain Modules:
- Ethereum and Stellar implementations in the “blockchain” directory with separate configuration files, utilities, and transaction handling.

##### Relationships and Interactions
- The blockchain components (both in backend and in the standalone blockchain directory) interact with external blockchain networks (Ethereum and Stellar) using configuration parameters provided in the .env file.
- External APIs are used for fiat integration (Flutterwave for payment processing, Africa's Talking for USSD services). These should be shown as external entities interacting with the backend.
- A database component if applicable (referenced in backend/src/config/db.js) that supports persistent storage for user and transaction data.

##### Architectural Patterns & Important Details
- The backend appears modular and follows an MVC-like pattern (controllers, models, routes) with additional services for business logic, supporting a clean separation of concerns.
- The bridge functionality and blockchain modules indicate that the system is built with a microservice mindset within a monolith, separating blockchain interactions from fiat/payment processing.
- Security features (secure wallet management, input validation, real-time monitoring, and rate limiting) should be annotated as cross-cutting concerns across the architecture.
- The use of specialized utilities for transaction monitoring and fee calculation highlights a focus on financial accuracy and reliability.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Frontend Components
  subgraph "Frontend"
    FE_WalletDashboard["Wallet Dashboard"]:::frontend
    FE_BridgeInterface["Bridge Interface"]:::frontend
    FE_DepositForm["Deposit Form"]:::frontend
    FE_WithdrawForm["Withdraw Form"]:::frontend
    FE_TransactionMonitor["Transaction Monitor"]:::frontend
    FE_GlobalLayout["Global Layout & Pages"]:::frontend
  end

  %% Backend API Routes
  subgraph "Backend API Routes"
    BE_EthereumRoutes["Ethereum Routes"]:::backend
    BE_StellarRoutes["Stellar Routes"]:::backend
    BE_RateRoutes["Rates Routes"]:::backend
  end

  %% Backend Controllers
  subgraph "Backend Controllers"
    BE_BridgeController["Bridge Controller"]:::backend
    BE_EthereumController["Ethereum Controller"]:::backend
    BE_StellarController["Stellar Controller"]:::backend
    BE_RateController["Rate Controller"]:::backend
  end

  %% Backend Services
  subgraph "Backend Services"
    BE_BridgeService["Bridge Service"]:::backend
    BE_RateService["Rate Service"]:::backend
    BE_EthereumService["Ethereum Blockchain Service"]:::backend
    BE_StellarService["Stellar Blockchain Service"]:::backend
    BE_USSDService["USSD Service"]:::backend
  end

  %% Configuration & Utilities
  subgraph "Configuration & Utilities"
    BE_DBConfig["Database Config"]:::config
    BE_BlockchainConfig["Blockchain Config"]:::config
    BE_ErrorHandler["Error Handler"]:::config
    BE_FeeCalculator["Fee Calculator"]:::config
    BE_TransactionMonitor_Util["Transaction Monitor Utility"]:::config
    BE_ValidationUtils["Validation Utils"]:::config
    BE_BlockchainUtils["Blockchain Utils"]:::config
    BE_AfricanCurrencies["African Currencies"]:::config
  end

  %% Blockchain Modules
  subgraph "Blockchain Modules"
    BC_Ethereum["Ethereum Blockchain Module"]:::blockchain
    BC_Stellar["Stellar Blockchain Module"]:::blockchain
  end

  %% External Integrations
  subgraph "External Integrations"
    EXT_Flutterwave["Flutterwave API"]:::external
    EXT_AfricasTalking["Africa's Talking"]:::external
  end

  %% Connections: Frontend -> API Routes
  FE_WalletDashboard -->|"HTTP"| BE_RateRoutes
  FE_BridgeInterface -->|"HTTP"| BE_EthereumRoutes
  FE_BridgeInterface -->|"HTTP"| BE_StellarRoutes
  FE_DepositForm -->|"HTTP"| BE_BridgeController
  FE_WithdrawForm -->|"HTTP"| BE_BridgeController
  FE_TransactionMonitor -->|"HTTP"| BE_RateRoutes
  FE_GlobalLayout -->|"Loads"| BE_EthereumRoutes

  %% API Routes -> Controllers
  BE_EthereumRoutes --> BE_EthereumController
  BE_StellarRoutes --> BE_StellarController
  BE_RateRoutes --> BE_RateController

  %% Controllers -> Services
  BE_BridgeController --> BE_BridgeService
  BE_EthereumController --> BE_EthereumService
  BE_StellarController --> BE_StellarService
  BE_RateController --> BE_RateService

  %% Services -> Blockchain Modules and External Integrations
  BE_BridgeService -->|"Triggers"| BC_Ethereum
  BE_BridgeService -->|"Triggers"| BC_Stellar
  BE_BridgeService -->|"Calls"| EXT_Flutterwave
  BE_EthereumService -->|"Utilizes"| BC_Ethereum
  BE_StellarService -->|"Utilizes"| BC_Stellar
  BE_RateService -->|"Uses"| BE_AfricanCurrencies
  BE_USSDService -->|"Integrates"| EXT_AfricasTalking

  %% Services -> Configuration & Utilities
  BE_BridgeController -->|"Uses"| BE_DBConfig
  BE_BridgeService -->|"Uses"| BE_BlockchainUtils
  BE_EthereumService -->|"Uses"| BE_BlockchainUtils
  BE_StellarService -->|"Uses"| BE_BlockchainUtils
  BE_BridgeService -->|"Calculates"| BE_FeeCalculator
  BE_BridgeService -->|"Monitors"| BE_TransactionMonitor_Util
  BE_EthereumService -->|"Validates"| BE_ValidationUtils
  BE_StellarService -->|"Validates"| BE_ValidationUtils
  BE_RateService -->|"Fetches"| BE_AfricanCurrencies
  BE_EthereumService -->|"ConfiguredBy"| BE_BlockchainConfig
  BE_StellarService -->|"ConfiguredBy"| BE_BlockchainConfig

  %% Click Events for Component Mapping
  click BE_BridgeService "https://github.com/emmanuelist/crossflow/blob/main/backend/src/services/bridgeService.js"
  click BE_RateService "https://github.com/emmanuelist/crossflow/blob/main/backend/src/services/rateService.js"
  click BE_EthereumService "https://github.com/emmanuelist/crossflow/blob/main/backend/src/services/ethereumService.js"
  click BC_Ethereum "https://github.com/emmanuelist/crossflow/tree/main/blockchain/ethereum"
  click BE_StellarService "https://github.com/emmanuelist/crossflow/blob/main/backend/src/services/stellarService.js"
  click BC_Stellar "https://github.com/emmanuelist/crossflow/tree/main/blockchain/stellar"
  click BE_USSDService "https://github.com/emmanuelist/crossflow/blob/main/backend/src/services/ussdService.js"
  click BE_BridgeController "https://github.com/emmanuelist/crossflow/blob/main/backend/src/controllers/bridgeController.js"
  click BE_EthereumController "https://github.com/emmanuelist/crossflow/blob/main/backend/src/controllers/ethereumController.js"
  click BE_StellarController "https://github.com/emmanuelist/crossflow/blob/main/backend/src/controllers/stellarController.js"
  click BE_RateController "https://github.com/emmanuelist/crossflow/blob/main/backend/src/controllers/rateController.js"
  click BE_EthereumRoutes "https://github.com/emmanuelist/crossflow/blob/main/backend/src/routes/ethereumRoutes.js"
  click BE_StellarRoutes "https://github.com/emmanuelist/crossflow/blob/main/backend/src/routes/stellarRoutes.js"
  click BE_RateRoutes "https://github.com/emmanuelist/crossflow/blob/main/backend/src/routes/rateRoutes.js"
  click BE_DBConfig "https://github.com/emmanuelist/crossflow/blob/main/backend/src/config/db.js"
  click BE_BlockchainConfig "https://github.com/emmanuelist/crossflow/blob/main/backend/src/config/blockchainConfig.js"
  click BE_ErrorHandler "https://github.com/emmanuelist/crossflow/blob/main/backend/src/utils/errorHandler.js"
  click BE_FeeCalculator "https://github.com/emmanuelist/crossflow/blob/main/backend/src/utils/feeCalculator.js"
  click BE_TransactionMonitor_Util "https://github.com/emmanuelist/crossflow/blob/main/backend/src/utils/transactionMonitor.js"
  click BE_ValidationUtils "https://github.com/emmanuelist/crossflow/blob/main/backend/src/utils/validationUtils.js"
  click BE_BlockchainUtils "https://github.com/emmanuelist/crossflow/blob/main/backend/src/utils/blockchainUtils.js"
  click BE_AfricanCurrencies "https://github.com/emmanuelist/crossflow/blob/main/backend/src/utils/africanCurrencies.js"
  click FE_WalletDashboard "https://github.com/emmanuelist/crossflow/blob/main/frontend/components/Dashboard/WalletDashboard.tsx"
  click FE_BridgeInterface "https://github.com/emmanuelist/crossflow/blob/main/frontend/components/Dashboard/SwapForm.tsx"
  click FE_DepositForm "https://github.com/emmanuelist/crossflow/blob/main/frontend/components/Dashboard/DepositForm.tsx"
  click FE_WithdrawForm "https://github.com/emmanuelist/crossflow/blob/main/frontend/components/Dashboard/WithdrawForm.tsx"
  click FE_TransactionMonitor "https://github.com/emmanuelist/crossflow/blob/main/frontend/components/Dashboard/TransactionMonitor.tsx"
  click FE_GlobalLayout "https://github.com/emmanuelist/crossflow/blob/main/frontend/app/layout.tsx"

  %% Styles
  classDef frontend fill:#a3d5ff,stroke:#1a73e8,stroke-width:2px;
  classDef backend fill:#ffe699,stroke:#f4b400,stroke-width:2px;
  classDef config fill:#d9d2e9,stroke:#8e24aa,stroke-width:2px;
  classDef blockchain fill:#c2f0c2,stroke:#388e3c,stroke-width:2px;
  classDef external fill:#f9d6d5,stroke:#d32f2f,stroke-width:2px;
```
