# me-diru/spin architecture

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

- Interactive diagram: https://gitdiagram.com/me-diru/spin
- Repository: https://github.com/me-diru/spin

## Overview

##### Project Type and Purpose
- Spin is an open-source Rust monorepo implementing a CLI and runtime framework for composing and running WebAssembly microservices.
- It provides commands to build, serve, and manage “Spin applications” (Wasm components + manifests), and a runtime that loads those components into a Wasmtime engine, wires up triggers (HTTP, Redis, etc.), host interfaces (KV, SQL, variables), and handles inbound/outbound calls.

##### High-Level System Components
a. CLI Layer (src/bin + src/commands)
- Parses user commands (`spin build`, `spin up`, `spin new`, etc.)
- Delegates to subcommands: build, up, doctor, plugins, templates, etc.
b. Build & Package (crates/build + crates/componentize + crates/common)
- Reads spin.toml manifest (crates/manifest)
- Invokes language toolchains (Cargo, Go, etc.) to compile Wasm
- Generates OCI images or local bundles
c. Loader (crates/loader + crates/oci)
- Reads manifests, resolves component binaries (local files, HTTP, OCI registry)
- Caches artifacts
- Verifies digests, applies file preopens and mounts
d. Runtime Core (crates/core + crates/trigger + crates/trigger-http + crates/trigger-redis + …)
- Initializes Wasmtime engine with component model
- Instantiates host interfaces / host components for:
- HTTP inbound triggers (crates/trigger-http)
- Redis inbound triggers (crates/trigger-redis)
- Outbound HTTP, Redis, MQTT, SQL (crates/outbound-*)
- KV storage, SQLite, MySQL, Postgres (crates/key-value-*, crates/sqlite-*)
- Variables provider (crates/variables, azure, env, vault)
- Telemetry (crates/telemetry)
- Manages component lifecycles, call routing, concurrency
e. Application Components (user Wasm binaries)
- Conform to the WebAssembly Component ABI (Wit interfaces in wit/)
- Invoked by runtime in response to triggers or API calls
f. External Services
- HTTP clients & servers
- Redis, SQL databases
- OCI registries
- Vault / environment variable stores
- Observability stack (Prometheus, Grafana, etc., under hack/o11y-stack)

##### Relationships and Data Flows
- CLI → Build submodule: reads spin.toml → invokes Cargo/Go → outputs .wasm + updated manifest
- CLI (`spin up`) → Loader: loads manifest & component binaries → Runtime Core
- Runtime Core → Wasmtime Engine → Instantiates component with host components
- Inbound Trigger (e.g., HTTP) → Runtime Core → Component’s exported handler → host interfaces
- Component calls host interface → Runtime Core → External service (e.g., writes KV) → returns to component
- Telemetry hooks intercept calls for metrics/traces

##### Architectural Patterns & Principles
- Microkernel/Plugin: Core engine + pluggable host interfaces (crates/outbound-*, crates/trigger-*)
- Component Model: uses WebAssembly component model (Wit definitions) to decouple language SDKs
- Layered CLI: command dispatch layers in src/commands
- Monorepo: each concern in a separate crate under crates/
- Clear separation of concerns: build vs. load vs. runtime vs. triggers vs. host protocols

##### Essential Elements
- Wasmtime engine at the center, since it’s the “kernel.”
- Manifest → loader → runtime path.
- Extensibility: plugin manager (crates/plugins) hooking into CLI and runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Application"
        direction TB
        CLI["CLI Layer"]:::cli
        SubBuild["spin build"]:::cli
        SubUp["spin up"]:::cli
        SubNew["spin new"]:::cli
        CLI --> SubBuild
        CLI --> SubUp
        CLI --> SubNew
    end
    click CLI "https://github.com/me-diru/spin/blob/main/src/bin/spin.rs"
    click SubBuild "https://github.com/me-diru/spin/tree/main/src/commands/"
    click SubUp "https://github.com/me-diru/spin/tree/main/src/commands/"
    click SubNew "https://github.com/me-diru/spin/tree/main/src/commands/"

    %% Build Pipeline
    subgraph "Build Pipeline" 
        direction TB
        MP["Manifest Parser"]:::build
        CU["Common Utilities"]:::build
        LTI["Language Toolchain Integration"]:::build
        MP --> CU
        CU --> LTI
    end
    click MP "https://github.com/me-diru/spin/tree/main/crates/manifest/src/"
    click CU "https://github.com/me-diru/spin/tree/main/crates/common/src/"
    click LTI "https://github.com/me-diru/spin/tree/main/crates/build/src/"
    click LTI "https://github.com/me-diru/spin/tree/main/crates/componentize/src/"

    %% Loader Service
    subgraph "Loader Service"
        direction TB
        ManifestLoader["Manifest & Artifacts Loader"]:::runtime
        OCIClient["OCI Registry Client"]:::runtime
        CacheMgr["Cache Manager"]:::runtime
        ManifestLoader --> OCIClient
        OCIClient --> CacheMgr
    end
    click ManifestLoader "https://github.com/me-diru/spin/tree/main/crates/loader/src/"
    click OCIClient "https://github.com/me-diru/spin/tree/main/crates/oci/src/"

    %% Runtime Core
    subgraph "Runtime Core"
        direction TB
        CoreEngine["Wasmtime Engine"]:::runtime
        CompStore["Component Store"]:::runtime
        TriggerMgr["Trigger Manager"]:::runtime
        HostCompMgr["Host Component Manager"]:::runtime
        CoreEngine --> CompStore
        CoreEngine --> TriggerMgr
        CoreEngine --> HostCompMgr
    end
    click CoreEngine "https://github.com/me-diru/spin/tree/main/crates/core/src/"
    click TriggerMgr "https://github.com/me-diru/spin/tree/main/crates/trigger/src/"
    click HostCompMgr "https://github.com/me-diru/spin/tree/main/crates/plugins/src/"

    %% Host Interfaces
    subgraph "Host Interfaces"
        direction TB
        HTTPTrigger["HTTP Inbound Trigger"]:::host
        RedisTrigger["Redis Inbound Trigger"]:::host
        OutHTTP["Outbound HTTP"]:::host
        OutMQTT["Outbound MQTT"]:::host
        OutMySQL["Outbound MySQL"]:::host
        OutPG["Outbound PostgreSQL"]:::host
        OutRedis["Outbound Redis"]:::host
        KV["Key-Value Store"]:::host
        KVAzure["KV Azure"]:::host
        KVRedis["KV Redis"]:::host
        KVSQLite["KV SQLite"]:::host
        SQLite["SQLite Host Interface"]:::host
        Variables["Variables Provider"]:::host
        Telemetry["Telemetry (metrics/tracing)"]:::host

        HostCompMgr --> HTTPTrigger
        HostCompMgr --> RedisTrigger
        HostCompMgr --> OutHTTP
        HostCompMgr --> OutMQTT
        HostCompMgr --> OutMySQL
        HostCompMgr --> OutPG
        HostCompMgr --> OutRedis
        HostCompMgr --> KV
        KV --> KVAzure
        KV --> KVRedis
        KV --> KVSQLite
        HostCompMgr --> SQLite
        HostCompMgr --> Variables
        HostCompMgr --> Telemetry
    end
    click HTTPTrigger "https://github.com/me-diru/spin/tree/main/crates/trigger-http/src/"
    click RedisTrigger "https://github.com/me-diru/spin/tree/main/crates/trigger-redis/src/"
    click OutHTTP "https://github.com/me-diru/spin/tree/main/crates/outbound-http/src/"
    click OutMQTT "https://github.com/me-diru/spin/tree/main/crates/outbound-mqtt/src/"
    click OutMySQL "https://github.com/me-diru/spin/tree/main/crates/outbound-mysql/src/"
    click OutPG "https://github.com/me-diru/spin/tree/main/crates/outbound-pg/src/"
    click OutRedis "https://github.com/me-diru/spin/tree/main/crates/outbound-redis/src/"
    click KV "https://github.com/me-diru/spin/tree/main/crates/key-value/src/"
    click KVAzure "https://github.com/me-diru/spin/tree/main/crates/key-value-azure/src/"
    click KVRedis "https://github.com/me-diru/spin/tree/main/crates/key-value-redis/src/"
    click KVSQLite "https://github.com/me-diru/spin/tree/main/crates/key-value-sqlite/src/"
    click SQLite "https://github.com/me-diru/spin/tree/main/crates/sqlite/src/"
    click Variables "https://github.com/me-diru/spin/tree/main/crates/variables/src/"
    click Telemetry "https://github.com/me-diru/spin/tree/main/crates/telemetry/src/"

    %% External Services
    subgraph "External Services"
        direction TB
        ExternalHTTP["HTTP Clients/Servers"]:::external
        ExternalRedis["Redis Database"]:::external
        ExternalSQL["SQL Databases"]:::external
        OCIRegistry["OCI Registry"]:::external
        Vault["Vault/Env Store"]:::external
        Observability["Observability Stack"]:::external

        ExternalHTTP
        ExternalRedis
        ExternalSQL
        OCIRegistry
        Vault
        Observability
    end
    click Observability "https://github.com/me-diru/spin/tree/main/hack/o11y-stack/"

    %% Data Flows
    SubBuild --> MP
    SubBuild --> CU
    SubBuild --> LTI
    SubUp --> ManifestLoader
    ManifestLoader --> CoreEngine
    CoreEngine -->|"instantiate component"| CoreEngine
    HTTPTrigger --> CoreEngine
    RedisTrigger --> CoreEngine
    CoreEngine -->|"calls host interface"| OutHTTP
    CoreEngine --> OutRedis
    CoreEngine --> OutMySQL
    CoreEngine --> OutPG
    CoreEngine --> OCIRegistry
    CoreEngine --> ExternalHTTP
    CoreEngine --> ExternalRedis
    CoreEngine --> ExternalSQL
    CoreEngine --> Vault
    Telemetry --> Observability

    %% Styles
    classDef cli fill:#a8d0e6,stroke:#333,stroke-width:1px
    classDef build fill:#b0e57c,stroke:#333,stroke-width:1px
    classDef runtime fill:#a2e6a8,stroke:#333,stroke-width:1px
    classDef host fill:#f1c453,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
```
