# spinframework/spin architecture

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

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

## Overview

##### Project type and purpose
- Spin is an open-source, CLI-driven framework (monorepo in Rust) for building, distributing, and running fast, secure WebAssembly microservices on Wasmtime.
- It provides a `spin` binary (in src/bin/spin.rs) with subcommands (build, up, new, doctor, plugins, etc.), a modular build pipeline, a manifest/loader subsystem, a runtime engine, host integrations (triggers + APIs), and an extensible plugin system.

##### File structure
- Top‐level:
- `.github`, `.devcontainer` – CI, container config
- `docs/`, `examples/` – user docs and sample apps
- `src/` – the CLI binary + command modules
- `crates/` – ~80 Cargo crates grouped by function
- `tests/` – integration, conformance, runtime tests
- `crates/` breakdown (key folders):
- **CLI & common**: crates/common, crates/plugins
- **Build/packaging**: crates/build, crates/componentize, crates/factors-*, crates/factors-executor
- **Manifest & loader**: crates/manifest, crates/loader, crates/oci
- **Runtime engine**: crates/core, crates/app
- **Triggers/adapters**: crates/trigger-http, crates/trigger-redis, crates/http, crates/key-value-*, crates/llm-*, crates/outbound-*
- **Utilities**: crates/telemetry, crates/variables, crates/templates, crates/doctor

##### README for additional insights
- Describes the CLI’s role in scaffolding apps (`spin new`), building them (`spin build`), running them (`spin up`).
- Mentions the WebAssembly component model, Wasmtime, supported triggers (HTTP, Redis), APIs (outbound HTTP, KV, SQL, variables, telemetry), and custom triggers via extension.

a. **CLI Frontend** (green):
- `spin` binary → parses args (crates/common) → dispatches to subcommand modules (`src/commands/*`) or plugins (crates/plugins).
b. **Build Subsystem** (blue):
- `spin build` → crates/build orchestrates → invokes cargo or cross (build.rs) → crates/componentize wraps wasm + WIT into a Spin component → crates/factors-* run analyzer/factor passes → emits .wasm/.component.
c. **Manifest & Loader** (purple):
- `spin up` → crates/loader fetches & caches artifacts (local filesystem or OCI via crates/oci) → crates/manifest parses, validates, normalizes `spin.toml`.
d. **Runtime Engine** (teal):
- crates/core (a Wasmtime‐based host) loads Spin component(s) → crates/app composes multiple components/triggers → spawns guest instances.
e. **Triggers & Host APIs** (orange):
- Inbound triggers: crates/trigger-http (HTTP server), crates/trigger-redis (Redis subscriber)
- Host function adapters: crates/http (WASI HTTP/Wagi), crates/key-value-*, crates/llm-*, crates/outbound-*, crates/variables, crates/telemetry
- Each adapter implements WIT interface for guest modules.
f. **External Services** (gray):
- HTTP clients/servers, Redis, MySQL/Postgres/SQLite, OCI registries, Vault/key-value stores, external telemetry backends.

1. User → CLI parses args
2. CLI → Build (→ cargo → componentize → factors → artifact)
3. CLI → Loader → Manifest → OCI fetch → Component(s)
4. CLI → Runtime Engine ← Component(s) + Host API adapters
5. Runtime Engine ↔ Inbound triggers (HTTP/Redis)
6. Guest module ↔ Host APIs ↔ External services

##### Architectural patterns & design principles
- **Micro-kernel**: core runtime + plug-in host functions for triggers/APIs
- **Modular crates**: one crate per concern (build, loader, manifest, runtime, triggers, APIs, telemetry, plugins)
- **Interface boundaries**: clear WIT/WASI interfaces between host (Rust) and guest (Wasm)
- **Command dispatcher**: the CLI uses subcommand modules + plugin hooks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Plugins
    subgraph "CLI & Plugins"
        direction TB
        SpinCLI["spin binary\n(src/bin/spin.rs)"]:::green
        Commands["Subcommands\n(src/commands/*)"]:::green
        Common["Argument Parsing / UI\n(crates/common)"]:::green
        Plugins["CLI Plugin Manager\n(crates/plugins)"]:::green
    end

    %% Build Subsystem
    subgraph "Build Subsystem"
        direction TB
        Build["Build Orchestrator\n(crates/build)"]:::blue
        Componentize["Componentizer\n(crates/componentize)"]:::blue
        FactorsDerive["Factor Derive\n(crates/factors-derive)"]:::blue
        Factors["Factor Pipeline\n(crates/factors)"]:::blue
        FactorsExec["Factor Executor\n(crates/factors-executor)"]:::blue
    end

    %% Manifest & Loader
    subgraph "Manifest & Loader"
        direction TB
        Manifest["Manifest Parser\n(crates/manifest)"]:::purple
        Loader["Artifact Loader\n(crates/loader)"]:::purple
        OCI["OCI Integration\n(crates/oci)"]:::purple
    end

    %% Runtime Engine
    subgraph "Runtime Engine"
        direction TB
        Core["Wasmtime Host\n(crates/core)"]:::teal
        App["App Composer\n(crates/app)"]:::teal
    end

    %% Triggers & Host APIs
    subgraph "Inbound Triggers" 
        direction TB
        TriggerHTTP["HTTP Trigger\n(crates/trigger-http)"]:::orange
        TriggerRedis["Redis Trigger\n(crates/trigger-redis)"]:::orange
    end

    subgraph "Host API Adapters"
        direction TB
        HostHTTP["WASI HTTP/Wagi\n(crates/http)"]:::orange
        HostKV["Key-Value Stores\n(crates/key-value-aws,\nkey-value-azure,\nkey-value-redis,\nkey-value-spin)"]:::orange
        HostLLM["LLM Functions\n(crates/llm-local,\ncrates/llm-remote-http)"]:::orange
        HostOutbound["Outbound Networking & DB\n(crates/factor-outbound-*)"]:::orange
        HostVars["Variables\n(crates/variables)"]:::orange
        HostTelem["Telemetry\n(crates/telemetry)"]:::orange
    end

    %% Templates & Diagnostics
    subgraph "Templates & Diagnostics"
        direction TB
        Templates["Project Scaffolding\n(crates/templates)"]:::green
        Doctor["Health Checks\n(crates/doctor)"]:::green
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ExtHTTP["HTTP Clients/Servers"]:::gray
        ExtRedis["Redis"]:::gray
        ExtDB["MySQL/Postgres/SQLite"]:::gray
        ExtOCI["OCI Registries"]:::gray
        ExtKV["Vault/Key-Value Stores"]:::gray
        ExtTelem["Telemetry Backends"]:::gray
    end

    %% Workflow Arrows
    SpinCLI -->|"1 parse args"| Common
    SpinCLI -->|"1 dispatch"| Commands
    Commands -->|"2 execute build"| Build
    Build -->|"2.1 wrap wasm"| Componentize
    Componentize -->|"2.2 derive factors"| FactorsDerive
    FactorsDerive -->|"2.3 factor pipeline"| Factors
    Factors -->|"2.4 run passes"| FactorsExec
    FactorsExec -->|"artifact (.wasm/.component)"| Loader

    Commands -->|"3 execute up"| Loader
    Loader -->|"3.1 fetch artifacts"| OCI
    OCI -->|"3.2 pull from registry"| ExtOCI
    Loader -->|"3.3 provide components"| Manifest
    Manifest -->|"3.4 parse/validate spin.toml"| Doctor

    Manifest -->|"4 load config"| Core
    Loader -->|"4 load components"| Core
    Core -->|"4 compose apps"| App

    App -->|"5 spawn triggers"| TriggerHTTP
    App --> TriggerRedis

    Core -->|"6 host call"| HostHTTP
    Core --> HostKV
    Core --> HostLLM
    Core --> HostOutbound
    Core --> HostVars
    Core --> HostTelem

    HostHTTP --> ExtHTTP
    HostKV --> ExtKV
    HostLLM --> ExtHTTP
    HostOutbound --> ExtDB
    HostOutbound --> ExtRedis
    HostOutbound --> ExtOCI
    HostVars --> ExtKV
    HostTelem --> ExtTelem

    %% Click Events
    click SpinCLI "https://github.com/spinframework/spin/blob/main/src/bin/spin.rs"
    click Commands "https://github.com/spinframework/spin/tree/main/src/commands/"
    click Common "https://github.com/spinframework/spin/tree/main/crates/common"
    click Plugins "https://github.com/spinframework/spin/tree/main/crates/plugins"
    click Build "https://github.com/spinframework/spin/tree/main/crates/build"
    click Componentize "https://github.com/spinframework/spin/tree/main/crates/componentize"
    click FactorsDerive "https://github.com/spinframework/spin/tree/main/crates/factors-derive"
    click Factors "https://github.com/spinframework/spin/tree/main/crates/factors"
    click FactorsExec "https://github.com/spinframework/spin/tree/main/crates/factors-executor"
    click Manifest "https://github.com/spinframework/spin/tree/main/crates/manifest"
    click Loader "https://github.com/spinframework/spin/tree/main/crates/loader"
    click OCI "https://github.com/spinframework/spin/tree/main/crates/oci"
    click Core "https://github.com/spinframework/spin/tree/main/crates/core"
    click App "https://github.com/spinframework/spin/tree/main/crates/app"
    click TriggerHTTP "https://github.com/spinframework/spin/tree/main/crates/trigger-http"
    click TriggerRedis "https://github.com/spinframework/spin/tree/main/crates/trigger-redis"
    click HostHTTP "https://github.com/spinframework/spin/tree/main/crates/http"
    click HostKV "https://github.com/spinframework/spin/tree/main/crates/key-value-aws"
    click HostLLM "https://github.com/spinframework/spin/tree/main/crates/llm-local"
    click HostOutbound "https://github.com/spinframework/spin/tree/main/crates/factor-outbound-http"
    click HostVars "https://github.com/spinframework/spin/tree/main/crates/variables"
    click HostTelem "https://github.com/spinframework/spin/tree/main/crates/telemetry"
    click Templates "https://github.com/spinframework/spin/tree/main/crates/templates"
    click Doctor "https://github.com/spinframework/spin/tree/main/crates/doctor"

    %% Styles
    classDef green fill:#e6ffe6,stroke:#00cc00,stroke-width:1px
    classDef blue fill:#e6f2ff,stroke:#0073e6,stroke-width:1px
    classDef purple fill:#f3e6ff,stroke:#9933cc,stroke-width:1px
    classDef teal fill:#e6ffff,stroke:#33cccc,stroke-width:1px
    classDef orange fill:#fff2e6,stroke:#ff8000,stroke-width:1px
    classDef gray fill:#f2f2f2,stroke:#808080,stroke-width:1px
```
