# wasmcloud/wadm architecture

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

- Interactive diagram: https://gitdiagram.com/wasmcloud/wadm
- Repository: https://github.com/wasmcloud/wadm

## Overview

##### Main Components

a) Core System Components:
- NATS Message Bus (central communication hub)
- Storage System (NATS KV Store)
- API Server
- Event Consumers
- Command Workers
- Scalers
- State Observer

b) External Integration Points:
- wasmCloud Hosts
- OCI Registries
- Client Applications (wash CLI)

##### Key Architectural Patterns

- Event-driven architecture
- Control loop pattern
- Publisher/Subscriber pattern
- State management system

##### Detailed Component Breakdown

a) Server Layer:
**/crates/wadm/src/server/**
- API Handlers
- Storage Interface
- Event Notifier
- Manifest Parser

b) Scaler System:
**/crates/wadm/src/scaler/**
- Config Scaler
- Daemon Scaler
- Spread Scaler
- Secret Scaler
- Status Scaler

c) Event System:
**/crates/wadm/src/events/**
- Event Serialization
- Event Deserialization
- Event Types

##### Data Flow Representation

- Command flow from API to workers
- Event flow from wasmCloud hosts through NATS
- State updates through the system
- Scaling decisions to host commands

##### Implementation Details

**┌─────────────────────────────────────────────────────┐**
- wadm                            │
- ┤

- ┌─────────┐    ┌──────────┐    ┌──────────────┐   │
- API    │━━━>│ Command  │━━━>│    Scaler    │   │
- Server  │    │ Workers  │    │   System     │   │
- ┘    └──────────┘    └──────────────┘   │
- ▲              ▲               │              │
- ▼              │
- ┌─────────┐    ┌──────────┐    ┌──────────────┐   │
- Storage │<───│  Event   │<───│    State     │   │
- (KV)   │    │Consumers │    │   Observer   │   │
- ┘    └──────────┘    └──────────────┘   │

- ┘

##### Integration Points

Connections to:
- wasmCloud hosts via NATS
- OCI registries for component retrieval
- Client tools (wash CLI)
- Multiple lattices (if applicable)

##### Scaling and HA

A section showing:
- Multiple wadm instances
- Load distribution
- State synchronization
- Failover paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Systems"]
        NATS[NATS Message Bus]:::external
        OCI[OCI Registries]:::external
        WASH[wash CLI]:::external
        HOSTS[wasmCloud Hosts]:::external
    end

    subgraph Core["Core wadm System"]
        subgraph API["API Layer"]
            APIS[API Server]:::core
            HAND[API Handlers]:::core
            PARS[Manifest Parser]:::core
            STOR_IF[Storage Interface]:::core
            NOTIF[Event Notifier]:::core
        end

        subgraph Storage["Storage Layer"]
            KV[NATS KV Store]:::storage
            STATE_MGT[State Management]:::storage
            SNAP[Snapshot Handler]:::storage
        end

        subgraph Events["Event System"]
            EV_TYPES[Event Types]:::event
            EV_SER[Event Serialization]:::event
            EV_DES[Event Deserialization]:::event
        end

        subgraph Workers["Worker Layer"]
            CMD_WORK[Command Worker]:::worker
            EV_WORK[Event Worker]:::worker
        end

        subgraph Scalers["Scaler System"]
            CONFIG_S[Config Scaler]:::scaler
            DAEMON_S[Daemon Scaler]:::scaler
            SPREAD_S[Spread Scaler]:::scaler
            SECRET_S[Secret Scaler]:::scaler
            STATUS_S[Status Scaler]:::scaler
        end

        subgraph Consumers["Consumer Layer"]
            CMD_CONS[Command Consumer]:::consumer
            EV_CONS[Event Consumer]:::consumer
        end

        OBS[State Observer]:::core
    end

    %% Connections
    WASH --> APIS
    APIS --> NATS
    NATS --> HOSTS
    HOSTS --> NATS
    NATS --> CMD_CONS
    NATS --> EV_CONS
    CMD_CONS --> Workers
    EV_CONS --> Workers
    Workers --> Scalers
    Scalers --> OBS
    OBS --> KV
    KV --> NATS

    %% Click events
    click APIS "https://github.com/wasmCloud/wadm/tree/main/crates/wadm/src/server/"
    click HAND "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/server/handlers.rs"
    click PARS "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/server/parser.rs"
    click STOR_IF "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/server/storage.rs"
    click NOTIF "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/server/notifier.rs"
    click KV "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/storage/nats_kv.rs"
    click STATE_MGT "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/storage/state.rs"
    click SNAP "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/storage/snapshot.rs"
    click EV_TYPES "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/events/types.rs"
    click EV_SER "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/events/ser.rs"
    click EV_DES "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/events/deser.rs"
    click CMD_WORK "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/workers/command.rs"
    click EV_WORK "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/workers/event.rs"
    click CONFIG_S "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/scaler/configscaler.rs"
    click DAEMON_S "https://github.com/wasmCloud/wadm/tree/main/crates/wadm/src/scaler/daemonscaler/"
    click SPREAD_S "https://github.com/wasmCloud/wadm/tree/main/crates/wadm/src/scaler/spreadscaler/"
    click SECRET_S "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/scaler/secretscaler.rs"
    click STATUS_S "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/scaler/statusscaler.rs"
    click CMD_CONS "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/consumers/commands.rs"
    click EV_CONS "https://github.com/wasmCloud/wadm/blob/main/crates/wadm/src/consumers/events.rs"
    click OBS "https://github.com/wasmCloud/wadm/blob/main/src/observer.rs"

    %% Styles
    classDef core fill:#2374f7,stroke:#000,stroke-width:2px,color:#fff
    classDef storage fill:#9f27cf,stroke:#000,stroke-width:2px,color:#fff
    classDef event fill:#f7d223,stroke:#000,stroke-width:2px
    classDef worker fill:#23f7b3,stroke:#000,stroke-width:2px
    classDef scaler fill:#f72356,stroke:#000,stroke-width:2px,color:#fff
    classDef consumer fill:#23f756,stroke:#000,stroke-width:2px
    classDef external fill:#666,stroke:#000,stroke-width:2px,color:#fff
```
