How jamaljsr/polar works
Main Components
• Desktop Application (Electron-based): This encompasses both the Electron “main process” (under the “electron” folder) and the React “renderer process” (majority of the UI code is in “src/components” and elsewhere).
• Docker-Based Node Infrastructure: Polar leverages native Docker images to instantiate various blockchain and Lightning nodes (Bitcoin Core, LND, Core Lightning, Eclair, Taproot Assets, and Terminal functionalities). The “docker” folder contains all Dockerfiles and startup scripts for these nodes.
• Business Logic and Services: The “src/lib” directories hold service implementations for interacting with Docker (dockerService), handling lightning nodes (lightning, lnd, clightning, eclair), and managing bitcoin, tap, litd, and settings. This layer abstracts the logic that interacts with the nodes.
• UI/UX Components: The extensive “src/components” structure shows dedicated UI screens such as home, network management, node images, and network designer. These components interact with the state (managed via easy-peasy/Redux) and invoke business logic.
• IPC and Proxy Servers: The Electron main process is responsible for setting up IPC channels (see “src/lib/ipc” and “electron/appIpcListener.ts”) and proxy servers (for example, in “electron/lnd”, “electron/litd”, “electron/tapd”) to act as bridges between the UI and back-end logic/services.
• Testing/Dev/Build Infrastructure: The project includes folders and configuration files for end-to-end tests (“e2e”) and unit tests (in “src” alongside .spec.tsx files). Additionally, CI/CD is set up via GitHub workflows.
Relationships and Interactions
• The Renderer Process (React UI) communicates with the Main Process through IPC channels to request operations (e.g., starting/stopping nodes, executing Docker commands).
• The Main Process manages Electron’s native capabilities (window management, system tray, logging, etc.) and hosts proxy servers that forward API calls to the respective backend services.
• The backend business logic, encapsulated within “src/lib”, directly interacts with Docker through services that generate/modify Docker compose files, manage container lifecycles, and interface with blockchain/node APIs.
• Docker interacts externally to spawn local nodes based on the definitions in the “docker” directory. The various node types are mapped to specific services in “src/lib/bitcoin”, “src/lib/lightning”, and so forth.
• The state management layer (in “src/store”) integrates with the UI and business logic, ensuring the current network/node states are synchronized.
Architectural Patterns and Design Principles
• Separation of Concerns: The project clearly splits the UI (React components), Electron’s main process logic (node API and IPC), and backend services (Docker/node management), following an MVC-like or layered architecture.
• Proxy Design: Proxy servers (e.g., LND, Tapd) exist to abstract the relationship with external node APIs.
• Modularity & Extensibility: The “lib” and “components” directories are organized by feature (bitcoin, lightning, tap, etc.), enhancing modularity.
• Container-Based Integration: Docker is used extensively to provide isolated network node environments for local development.
Relevant Technologies, Frameworks, and Tools
• Electron – for desktop environment and IPC between UI and native processes.
• ReactJS with TypeScript – for the user interface.
• Docker – used to spin up blockchain and Lightning nodes.
• easy-peasy (Redux abstraction) – for state management.
• Additional libraries (Ant Design, emotion, react-i18next) for UX enhancements and internationalization.
• Testing tools (Jest, Testcafe) integrated with the project’s structure.