# caravan-bitcoin/caravan architecture

> Architecture diagram of the GitHub repository caravan-bitcoin/caravan, 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/caravan-bitcoin/caravan
- Repository: https://github.com/caravan-bitcoin/caravan

## Overview

Based on our analysis of both the file tree and README, this is a monorepo for the Caravan ecosystem—a set of Bitcoin-related FOSS projects built with Turborepo. The monorepo is split mainly between two top-level directories: one for applications (for instance, the Caravan Coordinator webapp found under apps/coordinator) and one for library packages (under packages, which include various modules like bip32, caravan-bitcoin, caravan-clients, caravan-fees, caravan-health, caravan-psbt, caravan-wallets, multisig, and more). There is also tooling (like changesets for versioning and Turborepo configuration files) that ties the entire ecosystem together.

##### Main Components
- Create distinct sections for the high-level parts of the monorepo:
– The “Apps” section (with emphasis on the Caravan Coordinator web application).
– The “Packages” section (listing utility libraries such as @caravan/bitcoin, @caravan/wallets, @caravan/clients, @caravan/psbt, etc.).
– The “Tooling & Infrastructure” section (including Turborepo, changesets, CI/CD pipelines via GitHub Actions, linting, testing, and Docker configurations).

##### Architectural Patterns & Design
- A modular design. The monorepo approach already isolates concerns:
- The app components (React components, client actions, reducers, hooks, etc.) reside in the coordinator (as seen in apps/coordinator/src).
- The supporting libraries in the “packages” directory are “scoped” (for example, @caravan/bitcoin, @caravan/wallets) and provide domain-specific logic (like processing Bitcoin transactions, key management, fee estimation, PSBT creation, etc.).
- Use clear separation of concerns: UI (Coordinator), business logic/libraries (various packages), and developer tooling pipelines.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Tooling & Infrastructure Section
    subgraph "Tooling & Infrastructure"
        TT["Turborepo / Monorepo Config"]:::tooling
        CS["Changesets"]:::tooling
        CI["CI/CD Pipelines"]:::tooling
    end

    %% Apps Section
    subgraph "Apps"
        APP["Caravan Coordinator (Web App)"]:::app
    end

    %% Packages Section
    subgraph "Packages"
        P1["@caravan/bitcoin"]:::package
        P2["@caravan/clients"]:::package
        P3["@caravan/fees"]:::package
        P4["@caravan/health"]:::package
        P5["@caravan/psbt"]:::package
        P6["@caravan/wallets"]:::package
        P7["Bip32"]:::package
        P8["Multisig"]:::package
    end

    %% Tooling supports Apps
    TT -->|"supports"| APP
    CS -->|"supports"| APP
    CI -->|"supports"| APP

    %% Tooling ensures Packages (representative arrows)
    TT -->|"ensures"| P1
    TT -->|"ensures"| P2
    TT -->|"ensures"| P3
    TT -->|"ensures"| P4
    TT -->|"ensures"| P5
    TT -->|"ensures"| P6
    TT -->|"ensures"| P7
    TT -->|"ensures"| P8

    %% Coordinator depends on Packages
    APP -->|"depends_on"| P1
    APP -->|"depends_on"| P2
    APP -->|"depends_on"| P3
    APP -->|"depends_on"| P4
    APP -->|"depends_on"| P5
    APP -->|"depends_on"| P6
    APP -->|"depends_on"| P7
    APP -->|"depends_on"| P8

    %% Shared utility: Packages using Multisig
    P1 -->|"uses"| P8
    P2 -->|"uses"| P8
    P3 -->|"uses"| P8
    P4 -->|"uses"| P8
    P5 -->|"uses"| P8
    P6 -->|"uses"| P8

    %% Click Events
    click APP "https://github.com/caravan-bitcoin/caravan/tree/main/apps/coordinator"
    click P1 "https://github.com/caravan-bitcoin/caravan/tree/main/packages/caravan-bitcoin"
    click P2 "https://github.com/caravan-bitcoin/caravan/tree/main/packages/caravan-clients"
    click P3 "https://github.com/caravan-bitcoin/caravan/tree/main/packages/caravan-fees"
    click P4 "https://github.com/caravan-bitcoin/caravan/tree/main/packages/caravan-health"
    click P5 "https://github.com/caravan-bitcoin/caravan/tree/main/packages/caravan-psbt"
    click P6 "https://github.com/caravan-bitcoin/caravan/tree/main/packages/caravan-wallets"
    click P7 "https://github.com/caravan-bitcoin/caravan/tree/main/packages/bip32"
    click P8 "https://github.com/caravan-bitcoin/caravan/tree/main/packages/multisig"
    click CS "https://github.com/caravan-bitcoin/caravan/blob/main/.changeset"
    click TT "https://github.com/caravan-bitcoin/caravan/tree/main/turbo.json and turbo/"
    click CI "https://github.com/caravan-bitcoin/caravan/tree/main/.github/workflows"

    %% Styles
    classDef tooling fill:#a2d9ce,stroke:#1abc9c,stroke-width:2px;
    classDef app fill:#ffeaa7,stroke:#fdcb6e,stroke-width:2px;
    classDef package fill:#fab1a0,stroke:#e17055,stroke-width:2px;
```
