# ark-network/ark architecture

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

- Interactive diagram: https://gitdiagram.com/ark-network/ark
- Repository: https://github.com/ark-network/ark

## Overview

##### Project Type and Purpose
- Ark is a monorepo implementing an off-chain Bitcoin transaction protocol.
- It comprises:
- `server` (“arkd”): Always-on Go daemon exposing gRPC/REST APIs.
- `client`: Single-key CLI tool for end users.
- `pkg/client-sdk`: Go and WASM SDK for programmatic access (browser, scripts).
- `common`: Shared domain code (crypto, data models).
- `api-spec`: Protobuf + OpenAPI definitions driving codegen.

##### High-Level File-Structure Analysis
- Top-level directories:
- `server/`: Hexagonal-architecture backend (interface → application → domain → ports → infrastructure).
- `client/`: CLI front end.
- `pkg/client-sdk/`: SDK layer with REST, gRPC, file/in-memory/SQL stores, WASM bindings.
- `common/`: Reusable types/logic.
- `api-spec/`: Source of truth for RPC and REST APIs.
- Config & CI:
- Dockerfile, docker-compose for regtest networks.
- GitHub workflows for build, tests, release.
- Build scripts: Makefiles at root, client, common, server.

##### Key README Insights
- Ark supports multiple Bitcoin networks via embedded `lnwallet` or RPC nodes.
- Exposes both gRPC and HTTP (via gRPC-Gateway / OpenAPI swagger).
- Uses Badger or SQLite adaptively for state, and Nostrum for event notifications.
- Authentication via macaroons integrated at gRPC interceptor layer.

##### Detail Level
- Essential components without overcrowding.
- If needed, split into two views:
- “Macro” overview showing Clients → Server → External Systems.
- “Server internals” focused on hexagonal layers and adapters.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        direction TB
        CLI["CLI Client"]:::clients
        GoSDK["Go SDK"]:::clients
        WASMSDK["WASM SDK"]:::clients
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        GRPC["gRPC Server"]:::api
        REST["gRPC-Gateway / REST"]:::api
    end

    %% Server Internals
    subgraph "Server Internals"
        direction TB
        Arkd["Ark Server Daemon (arkd)"]:::core
        subgraph "Interface Layer"
            direction TB
            GRPCHandlers["gRPC Handlers"]:::core
            GRPCInterceptors["gRPC Interceptors"]:::core
            GRPCService["Service Definition"]:::core
            Otel["OpenTelemetry (otel.go)"]:::support
        end
        AppServices["Application Services"]:::core
        Domain["Domain Model"]:::core
        Ports["Ports Definitions"]:::core
    end

    %% Infrastructure Adapters
    subgraph "Infrastructure Adapters"
        direction TB
        DB_Badger["DB Adapter: Badger"]:::infra
        DB_SQLite["DB Adapter: SQLite"]:::infra
        Notifier["Notifier (Nostr)"]:::infra
        Scheduler_Block["Scheduler: Block"]:::infra
        Scheduler_Gocron["Scheduler: gocron"]:::infra
        TxBuilder["Transaction Builder"]:::infra
        Unlocker_Env["Unlocker (env)"]:::infra
        Unlocker_File["Unlocker (file)"]:::infra
        Wallet["Wallet Adapter"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        BitcoinNodes["Bitcoin Nodes"]:::external
        KVDB["External KVDB / etcd"]:::external
    end

    %% Support Services
    subgraph "Support Services"
        direction TB
        Macaroons["Macaroon Auth Service"]:::support
    end

    %% Shared & Specs
    subgraph "Shared & API Specs"
        direction TB
        Common["Shared Domain Code"]:::shared
        Proto["API Spec: Protobuf"]:::shared
        OpenAPI["API Spec: OpenAPI"]:::shared
    end

    %% Connections
    CLI -->|gRPC / HTTP| GRPC
    GoSDK -->|gRPC| GRPC
    GoSDK -->|REST| REST
    WASMSDK -->|REST| REST

    GRPC --> GRPCHandlers
    REST --> GRPCHandlers

    GRPCHandlers --> GRPCInterceptors
    GRPCInterceptors --> Arkd
    Arkd --> AppServices
    AppServices --> Domain
    Domain --> Ports
    Ports --> DB_Badger
    Ports --> DB_SQLite
    Ports --> Notifier
    Ports --> Scheduler_Block
    Ports --> Scheduler_Gocron
    Ports --> TxBuilder
    Ports --> Unlocker_Env
    Ports --> Unlocker_File
    Ports --> Wallet

    DB_Badger --- BitcoinNodes
    DB_SQLite --- BitcoinNodes
    Notifier --- BitcoinNodes
    Scheduler_Block --- BitcoinNodes
    Scheduler_Gocron --- BitcoinNodes
    Wallet --- BitcoinNodes
    DB_Badger --- KVDB
    DB_SQLite --- KVDB

    GRPCInterceptors --> Macaroons
    GRPCInterceptors --> Otel

    Common -.-> AppServices
    Proto -.-> GRPCService
    OpenAPI -.-> REST

    %% Click Events
    click CLI "https://github.com/ark-network/ark/blob/master/client/main.go"
    click GoSDK "https://github.com/ark-network/ark/tree/master/pkg/client-sdk"
    click WASMSDK "https://github.com/ark-network/ark/tree/master/pkg/client-sdk/wasm/browser"
    click Arkd "https://github.com/ark-network/ark/tree/master/server/cmd/arkd"
    click GRPCHandlers "https://github.com/ark-network/ark/tree/master/server/internal/interface/grpc/handlers"
    click GRPCInterceptors "https://github.com/ark-network/ark/tree/master/server/internal/interface/grpc/interceptors"
    click GRPCService "https://github.com/ark-network/ark/blob/master/server/internal/interface/grpc/service.go"
    click AppServices "https://github.com/ark-network/ark/tree/master/server/internal/core/application"
    click Domain "https://github.com/ark-network/ark/tree/master/server/internal/core/domain"
    click Ports "https://github.com/ark-network/ark/tree/master/server/internal/core/ports"
    click DB_Badger "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/db/badger"
    click DB_SQLite "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/db/sqlite"
    click Notifier "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/notifier/nostr"
    click Scheduler_Block "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/scheduler/block"
    click Scheduler_Gocron "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/scheduler/gocron"
    click TxBuilder "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/tx-builder/covenantless"
    click Unlocker_Env "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/unlocker/env"
    click Unlocker_File "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/unlocker/file"
    click Wallet "https://github.com/ark-network/ark/tree/master/server/internal/infrastructure/wallet/btc-embedded"
    click Macaroons "https://github.com/ark-network/ark/tree/master/server/pkg/macaroons"
    click Otel "https://github.com/ark-network/ark/blob/master/server/internal/interface/grpc/otel.go"
    click Common "https://github.com/ark-network/ark/tree/master/common"
    click Proto "https://github.com/ark-network/ark/tree/master/api-spec/protobuf"
    click OpenAPI "https://github.com/ark-network/ark/tree/master/api-spec/openapi"

    %% Styles
    classDef clients fill:#D0E6FF,stroke:#0047AB,stroke-width:2px
    classDef api fill:#D4F7D4,stroke:#006400,stroke-width:2px
    classDef core fill:#FFF4C1,stroke:#D4A017,stroke-width:2px
    classDef infra fill:#FFE7C4,stroke:#B45F06,stroke-width:2px
    classDef external fill:#E0E0E0,stroke:#606060,stroke-width:2px
    classDef support fill:#E8D4F8,stroke:#800080,stroke-width:2px
    classDef shared fill:#CFFFE5,stroke:#008B8B,stroke-width:2px
```
