# ledgerhq/wallet-api architecture

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

- Interactive diagram: https://gitdiagram.com/ledgerhq/wallet-api
- Repository: https://github.com/ledgerhq/wallet-api

## Overview

##### Main Components
- API Specification & Core: This includes the “spec” folder (which contains the API docs for RPC, client, server, etc.) plus the “packages/core” folder that defines JSON-RPC, error handling, families, and core types.
- Client Implementation: Found within “packages/client” and “packages/client-react”, these federate the client side of the API. There’s also an example implementation under “examples/client-nextjs” that demonstrates how a front-end integrates the Wallet API, especially for React-based usage.
- Server Implementation: Located in “packages/server”, this part implements the server side of the Wallet API and includes internal handlers for specific modules (account, bitcoin, currency, etc.).
- Simulator & Tools: The “packages/simulator” enables testing and simulating different wallet interactions. Additionally, folders for “packages/manifest-validator-cli” and “packages/manifest-validator” provide tooling for validating dapp and wallet manifests.
- Documentation & Developer Tools: In “apps/docs” you have the documentation app (built with Next.js) that ties all the components and explains usage, while “apps/wallet-api-tools” provides additional UI tools around the API.
- Configuration & CI/CD: Notice the presence of various workflow configurations (.github/workflows), code style/linting (e.g., .eslintrc.js, .prettierrc), and version management (pnpm-workspace.yaml).

##### Relationships and Interactions
- The Client Implementation (in packages/client and client-react) acts as the consumer of the API and facilitates integration with front-end applications (e.g., the Next.js example).
- The Server Implementation (in packages/server) listens for JSON-RPC messages and dispatches them using the internal handlers from submodules. Underneath, this is built on top of the core (packages/core), which includes domain logic for accounts, currencies, and various supported crypto families.
- Tools like the Simulator and Manifest Validators work in tandem to test/validate the communication and interactions between clients and wallets.
- Documentation (apps/docs) and guides (rfc, spec folders) support developers along with CI/CD configurations ensuring quality and consistency.

##### Important Architectural Patterns and Design Principles
- Modularity: The monorepo is segmented into clearly defined packages (client, server, core, tools), enforcing separation of concerns.
- Extensibility: The structure for “families” in packages/core and the modular handlers in packages/server indicate an architecture ready to support many cryptocurrencies.
- Standard Interfaces: The use of JSON-RPC for communication suggests an emphasis on a standardized message-passing interface between wallet and application.
- Developer Experience: With thorough documentation, linting, CI/CD workflows, and examples, the project facilitates ease of integration and extension.

##### Final Checklist
- Every major package or component is represented with a clear label.
- Notes on how various subcomponents (like crypto family modules or internal handlers) fit within the larger architecture.
- A section for CI/CD and Developer Tools where applicable, to reflect modern development practices.

This level of detail will allow the principal software engineer to view the project as a network of interrelated modules—from core API definitions to client and server implementations along with testing/simulation infrastructure—all connected by the central JSON-RPC wallet interface that the project centers on.

## Diagram (Mermaid)

```mermaid
graph TD
    %% API Specification & Core (Left Column)
    subgraph "API Specification & Core"
        A1["Spec Documentation"]:::core
        A2["Core Functionality"]:::core
    end

    %% Client Implementation (Top)
    subgraph "Client Implementation"
        B1["Core Client Library"]:::client
        B2["React Client Library"]:::client
        B3["Next.js Example Integration"]:::client
    end

    %% Central Wallet API
    API["Wallet API (JSON-RPC)"]:::api

    %% Server Implementation (Bottom)
    subgraph "Server Implementation"
        C1["Server API and Handlers"]:::server
    end

    %% Simulator & Validator Tools (Right Upper)
    subgraph "Simulator & Validator Tools"
        D1["Simulator"]:::tools
        D2["Manifest Validator CLI"]:::tools
        D3["Manifest Validator"]:::tools
    end

    %% Documentation & Developer Tools (Right Lower)
    subgraph "Documentation & Developer Tools"
        E1["Documentation App"]:::docs
        E2["Wallet API Tools UI"]:::docs
    end

    %% Relationships from Client to API
    B1 -->|"JSON-RPC"| API
    B2 -->|"JSON-RPC"| API
    B3 -->|"JSON-RPC"| API

    %% Relationships from API to Server
    API -->|"JSON-RPC"| C1

    %% Relationships from API Specification & Core to API
    A1 -->|"defines"| API
    A2 -->|"supports"| API

    %% Relationships from API to Tools & Validators
    API -->|"testedBy"| D1
    API -->|"validatedBy"| D2
    API -->|"validatedBy"| D3

    %% Relationships from API to Documentation & Developer Tools
    API -->|"documentedBy"| E1
    API -->|"tools"| E2

    %% Class Definitions for colors
    classDef client fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef server fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef core fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef tools fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef docs fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef api fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/ledgerhq/wallet-api/tree/main/spec/"
    click A2 "https://github.com/ledgerhq/wallet-api/tree/main/packages/core/"
    click B1 "https://github.com/ledgerhq/wallet-api/tree/main/packages/client/"
    click B2 "https://github.com/ledgerhq/wallet-api/tree/main/packages/client-react/"
    click B3 "https://github.com/ledgerhq/wallet-api/tree/main/examples/client-nextjs/"
    click C1 "https://github.com/ledgerhq/wallet-api/tree/main/packages/server/"
    click D1 "https://github.com/ledgerhq/wallet-api/tree/main/packages/simulator/"
    click D2 "https://github.com/ledgerhq/wallet-api/tree/main/packages/manifest-validator-cli/"
    click D3 "https://github.com/ledgerhq/wallet-api/tree/main/packages/manifest-validator/"
    click E1 "https://github.com/ledgerhq/wallet-api/tree/main/apps/docs/"
    click E2 "https://github.com/ledgerhq/wallet-api/tree/main/apps/wallet-api-tools/"
```
