# jamaljsr/polar architecture

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

- Interactive diagram: https://gitdiagram.com/jamaljsr/polar
- Repository: https://github.com/jamaljsr/polar

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        ReactUI["React Renderer (UI)"]:::frontend
        StateMgmt["State Management (Store)"]:::frontend
    end

    subgraph "Application Layer"
        ElectronMain["Electron Main Process (IPC & Proxy)"]:::electron
        ElectronIPC["Electron IPC"]:::electron
        LNDProxy["LND Proxy Server"]:::electron
        LITDProxy["LITD Proxy Server"]:::electron
        TapdProxy["Tapd Proxy Server"]:::electron
    end

    subgraph "Services Layer"
        DockerMgmt["Docker Management Service"]:::services
        BitcoinSvc["Bitcoin Integration Service"]:::services
        LightningLND["Lightning: LND Service"]:::services
        LightningCL["Lightning: Core Lightning Service"]:::services
        LightningEclair["Lightning: Eclair Service"]:::services
        TapAssets["Taproot Assets & Custom Node Service"]:::services
    end

    subgraph "Infrastructure Layer"
        DockerNodes["Docker Nodes (Bitcoin, Lightning, etc.)"]:::infra
    end

    subgraph "Testing/CI"
        TestingCI["Testing, e2e, CI/CD"]:::testing
    end

    %% Interactions
    ReactUI -->|"IPC_request"| ElectronMain
    ReactUI --> StateMgmt

    ElectronMain -->|"Routes_IPC"| ElectronIPC
    ElectronMain -->|"Manages_Docker"| DockerMgmt
    ElectronMain -->|"Manages_Bitcoin"| BitcoinSvc
    ElectronMain -->|"Manages_LND"| LightningLND
    ElectronMain -->|"Manages_CL"| LightningCL
    ElectronMain -->|"Manages_Eclair"| LightningEclair
    ElectronMain -->|"Manages_TapAssets"| TapAssets

    DockerMgmt -->|"Triggers_Containers"| DockerNodes

    ElectronIPC --> LNDProxy
    ElectronIPC --> LITDProxy
    ElectronIPC --> TapdProxy

    TestingCI --- DockerMgmt
    TestingCI --- ReactUI

    %% Click Events
    click ElectronMain "https://github.com/jamaljsr/polar/blob/master/electron/appIpcListener.ts"
    click ElectronMain "https://github.com/jamaljsr/polar/blob/master/electron/index.ts"
    click ElectronMain "https://github.com/jamaljsr/polar/blob/master/electron/windowManager.ts"
    click ElectronMain "https://github.com/jamaljsr/polar/blob/master/electron/appMenu.ts"
    click ElectronMain "https://github.com/jamaljsr/polar/blob/master/electron/trayManager.ts"

    click ReactUI "https://github.com/jamaljsr/polar/tree/master/src/components"
    click DockerNodes "https://github.com/jamaljsr/polar/tree/master/docker"
    click DockerMgmt "https://github.com/jamaljsr/polar/tree/master/src/lib/docker"
    click BitcoinSvc "https://github.com/jamaljsr/polar/tree/master/src/lib/bitcoin"
    click LightningLND "https://github.com/jamaljsr/polar/tree/master/src/lib/lightning/lnd"
    click LightningCL "https://github.com/jamaljsr/polar/tree/master/src/lib/lightning/clightning"
    click LightningEclair "https://github.com/jamaljsr/polar/tree/master/src/lib/lightning/eclair"
    click TapAssets "https://github.com/jamaljsr/polar/tree/master/src/lib/tap"
    click ElectronIPC "https://github.com/jamaljsr/polar/tree/master/src/lib/ipc"
    click LNDProxy "https://github.com/jamaljsr/polar/blob/master/electron/lnd/lndProxyServer.ts"
    click LITDProxy "https://github.com/jamaljsr/polar/blob/master/electron/litd/litdProxyServer.ts"
    click TapdProxy "https://github.com/jamaljsr/polar/blob/master/electron/tapd/tapdProxyServer.ts"
    click StateMgmt "https://github.com/jamaljsr/polar/tree/master/src/store"
    click TestingCI "https://github.com/jamaljsr/polar/tree/master/e2e"

    %% Styles
    classDef frontend fill:#FFCCCC,stroke:#880000,stroke-width:2px;
    classDef electron fill:#CCFFCC,stroke:#008800,stroke-width:2px;
    classDef services fill:#CCCCFF,stroke:#000088,stroke-width:2px;
    classDef infra fill:#FFFFCC,stroke:#888800,stroke-width:2px;
    classDef testing fill:#FFEECC,stroke:#884400,stroke-width:2px;
```
