How pendulum-chain/vortex works
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.