# joinmarket-webui/jam architecture

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

- Interactive diagram: https://gitdiagram.com/joinmarket-webui/jam
- Repository: https://github.com/joinmarket-webui/jam

## Overview

##### Main Components
- Frontend Web Interface: The core of the project is in the “src” directory, which contains numerous React components, hooks, context providers, and styling files. This is the user-facing part that renders the wallet UI, handles routing, and manages state.
- Dockerized Dependencies: The “docker” directory shows configurations for different containerized services, particularly for a regtest setup. This includes:
– Dockerfiles and scripts for initiating a Bitcoin regtest environment (found under docker/regtest/dockerfile-deps/bitcoin) that simulates network conditions.
– Dockerfiles for JoinMarket components (e.g., joinmarket directory node, wallet services, and web UI standalone containers) that enable interaction with JoinMarket’s client-server architecture.
- External Services: The system automatically integrates with external services such as JoinMarket’s client-server (as referenced in the README) and potentially a Bitcoin node.

##### Relationships and Interactions
- The Browser/Client initiates requests to your React frontend.
- The frontend communicates with the API libraries (located in src/libs) and utilizes context providers to manage wallet state and service configurations.
– The Bitcoin regtest container (to simulate blockchain interactions).
– JoinMarket components (such as the wallet and directory node) that handle coinjoin transactions, orderbook viewing, fidelity bonds, and other wallet operations.
- Data flow: user-initiated wallet commands (sending funds, orderbook queries, etc.) propagate through the frontend, are routed via API abstraction layers, and then interact with the backend services within the Docker containers.

##### Important Architectural Patterns and Principles
- Separation of Concerns: The system delineates responsibilities clearly between UI (React components), business/API logic (libraries and context providers), and infrastructure (Dockerized services).
- Containerization and Microservices: The Docker setup clearly shows a microservices-like approach. Each major dependency (Bitcoin regtest, joinmarket wallet components) is isolated in its own container, which is important for clarity.
- Extensibility: The structure (e.g., modular React components, context providers) allows for adding new features like PayJoin support or additional wallet functionalities, which is also reflected in the roadmap in the README.
- Integration: The project integrates with JoinMarket’s ecosystem, and this external dependency along with potential integrations with different node systems (RaspiBlitz, Umbrel, etc.) should be clearly depicted.

##### Relevant Technologies and Frameworks
- React and TypeScript (from the source components).
- Docker and Docker Compose for container orchestration.
- API abstractions that likely perform HTTP/WS communications with JoinMarket services.
- CSS modules, context APIs, and hooks as core patterns in the frontend.
- Integration with external services like Bitcoin regtest nodes and JoinMarket’s backend API.

- Clear Labels: Label every block/component (e.g., “React Frontend”, “JoinMarket API Layer”, “Bitcoin Regtest Container”, “JoinMarket Wallet Service”, etc.).
- Grouping: It might be helpful to group all Docker containers within a “Containerized Services” umbrella to indicate their collaboration via docker-compose.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Browser["Browser/Client"]:::client

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["React Frontend"]:::frontend
    end

    %% API / Business Logic Layer
    subgraph "API / Business Logic Layer"
        APIM["API Modules"]:::apilayer
        CTX["Context Providers"]:::apilayer
        BL["Business Logic Aggregator"]:::apilayer
        APIM -->|"aggregate"| BL
        CTX -->|"aggregate"| BL
    end

    %% Containerized Services
    subgraph "Containerized Services"
        Bitcoin["Bitcoin Regtest Container"]:::docker
        Directory["JoinMarket Directory Node"]:::docker
        Wallet["JoinMarket Wallet Service"]:::docker
        WebUI["JoinMarket Web UI Container"]:::docker
        Directory -->|"internal"| Wallet
    end

    %% Connections between layers
    Browser -->|"HTTP/WS"| FE
    FE -->|"API call"| APIM
    FE -->|"API call"| CTX
    BL -->|"API_call"| Bitcoin
    BL -->|"API_call"| Directory
    BL -->|"API_call"| Wallet
    BL -->|"API_call"| WebUI

    %% Aggregating API Modules and Context Providers into BL
    APIM --- CTX
    APIM --- BL
    CTX --- BL

    %% Click Events
    click FE "https://github.com/joinmarket-webui/jam/tree/devel/src/components"
    click APIM "https://github.com/joinmarket-webui/jam/tree/devel/src/libs"
    click CTX "https://github.com/joinmarket-webui/jam/tree/devel/src/context"
    click Bitcoin "https://github.com/joinmarket-webui/jam/tree/devel/docker/regtest/dockerfile-deps/bitcoin/regtest-initializer"
    click Directory "https://github.com/joinmarket-webui/jam/tree/devel/docker/regtest/dockerfile-deps/joinmarket/directory_node"
    click Wallet "https://github.com/joinmarket-webui/jam/tree/devel/docker/regtest/dockerfile-deps/joinmarket/latest"
    click WebUI "https://github.com/joinmarket-webui/jam/tree/devel/docker/regtest/dockerfile-deps/joinmarket/webui-standalone"

    %% Styles
    classDef client fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef frontend fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef apilayer fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef docker fill:#DDA0DD,stroke:#800080,stroke-width:2px,stroke-dasharray: 5 5;
```
