# pendulum-chain/vortex architecture

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

- Interactive diagram: https://gitdiagram.com/pendulum-chain/vortex
- Repository: https://github.com/pendulum-chain/vortex

## Overview

##### Main Components
- Frontend Client:
- Located in the "src" directory.
- Built with React and Vite.
- Responsible for the user interface and user interactions (e.g., swap pages, account management, forms, and other UI components found in "src/components", "src/pages", etc.).
- Signer Service (Backend API):
- Found in the "signer-service" directory.
- Uses Express (note configuration in “src/config/express.ts”) and TypeScript.
- Contains controllers, routes, middlewares, and services to process requests (shown in subdirectories such as “api/controllers”, “api/routes/v1”, and “api/services”).
- Handles various blockchain-related operations such as interactions with smart contracts (e.g., use of ABIs in the "mooncontracts" directory), wallet connections, and payment processing.
- Blockchain/Smart Contracts Integration:
- The project includes smart contracts (e.g., “mooncontracts”), contracts in the “src/contracts” folder, and many services that interact with blockchains (Polkadot, Ethereum) via external APIs (like Alchemy).
- External Services and Integrations:
- Environmental variables (e.g., VITE_SIGNING_SERVICE_PATH, VITE_ALCHEMY_API_KEY) indicate that the system interacts with external signing services and RPC providers.
- There are also integrations for wallet connections, KYC procedures (BRLA components, KYC service hooks), fee comparison, and off-ramp payment flows.

##### Relationships and Interactions
- User actions (swaps, signing requests, KYC submissions) in the frontend trigger API calls.
- The API endpoints are defined in routes (for example, "/api/v1/siwe", "/api/v1/moonbeam", etc.).
- The Signer Service acts as an intermediary:
- It processes incoming requests through a layered architecture: routing → controllers → services → helper functions.
- It validates requests using middlewares and handles errors through a defined error handling mechanism.
- Blockchain communications:
- The signer-service and parts of the frontend (through contract wrappers located in “src/contracts”) interact with blockchain nodes (Ethereum, Polkadot) and use integrated tools like Alchemy or wallet signers.
- There is also a clear boundary between on-chain (smart contracts) and off-chain processing (API business logic).
- DevOps and Deployment:
- GitHub workflows (under ".github/workflows") and Docker-related configurations (e.g., signer-service/Dockerfile) indicate containerized deployment and CI/CD pipelines.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- The system clearly divides UI rendering (frontend) from business logic and blockchain interactions (signer-service backend).
- Modular Design:
- The backend API is organized into controllers, routes, services, and middlewares.
- The frontend is structured by components, hooks, contexts, and services.
- Reusability and Extensibility:
- Modules such as “hooks” for connecting to Polkadot wallets and “services” for handling blockchain transactions facilitate future enhancements.
- Microservices or API Layer:
- Although not split into separate microservices, the signer-service forms an isolated backend that could be scaled independently of the frontend.

##### Detailed Steps for the Principal Software Engineer
- the Frontend (React/Vite app) and
- the Backend (Signer Service).
- Under the Backend block, subdivide into:
- API Routing (controllers, routes),
- Business Logic (services for blockchain, KYC, fee calculation, etc.),
- Error Handling (error and validator middlewares),
- Configuration and Integration Layers (external APIs, blockchain nodes).
- A separate block for Blockchain/Smart Contracts:
- “mooncontracts” and “src/contracts” components.
- Interactions such as on-chain transaction signing and validation.
- From the Frontend to the Backend to represent REST API calls.
- From the Backend to the Blockchain block to show outgoing transactions or query calls.
- Incorporate details:
- Annotations for environment-specific endpoints and deployment mechanisms.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend (React/Vite)"
        F1["Frontend Client (React/Vite)"]:::frontend
        F2["UI Components"]:::frontend
    end

    %% Signer Service Layer
    subgraph "Signer Service (Express API)"
        B1["Signer Service"]:::backend
        C1["Express Config"]:::backend
        C2["Controllers"]:::backend
        C3["Routes"]:::backend
        C4["Services"]:::backend
    end

    %% Blockchain & Smart Contracts Layer
    subgraph "Blockchain & Smart Contracts"
        BC1["Mooncontracts"]:::blockchain
        BC2["Contracts"]:::blockchain
    end

    %% Connections between layers
    F1 -->|"API_calls"| C3
    C3 -->|"routes_to"| C2
    C1 -->|"configures"| C2
    C2 -->|"calls"| C4
    C4 -->|"blockchain_actions"| BC1
    C4 -->|"blockchain_actions"| BC2

    %% Click Events
    click F1 "https://github.com/pendulum-chain/vortex/tree/staging/src"
    click F2 "https://github.com/pendulum-chain/vortex/tree/staging/src/components"
    click B1 "https://github.com/pendulum-chain/vortex/tree/staging/signer-service"
    click C1 "https://github.com/pendulum-chain/vortex/blob/staging/signer-service/src/config/express.ts"
    click C2 "https://github.com/pendulum-chain/vortex/tree/staging/signer-service/src/api/controllers"
    click C3 "https://github.com/pendulum-chain/vortex/tree/staging/signer-service/src/api/routes/v1"
    click C4 "https://github.com/pendulum-chain/vortex/tree/staging/signer-service/src/api/services"
    click BC1 "https://github.com/pendulum-chain/vortex/tree/staging/mooncontracts"
    click BC2 "https://github.com/pendulum-chain/vortex/tree/staging/src/contracts"

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:2px;
    classDef backend fill:#cfc,stroke:#333,stroke-width:2px;
    classDef blockchain fill:#ffc,stroke:#333,stroke-width:2px;
```
