# yourikka/minicloud architecture

> Architecture diagram of the GitHub repository yourikka/minicloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yourikka/minicloud
- Repository: https://github.com/yourikka/minicloud

## Overview

MiniCloud is a single-process development platform for admitting and serving WASI WebAssembly functions. The principal workflow is management API writes for a Function, artifact, validated immutable Version, and Route; the local serving projection then converges, letting callers invoke the published function through the HTTP Gateway and Worker. The graph preserves those domain stages and the validator, execution, and worker-serving layers. The README documents the process composition; sampled source confirms key handler and validation behavior, but several internal links rely on that documented composition.

Main entry points: [`internal/localcontroller/controller.go`](https://github.com/yourikka/minicloud/blob/main/internal/localcontroller/controller.go) (Local Controller), [`internal/workeragent/agent.go`](https://github.com/yourikka/minicloud/blob/main/internal/workeragent/agent.go) (Worker Agent), [`internal/localcore/runtime.go`](https://github.com/yourikka/minicloud/blob/main/internal/localcore/runtime.go) (Process Composition), [`internal/localserving/sync.go`](https://github.com/yourikka/minicloud/blob/main/internal/localserving/sync.go) (Serving Projection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Management and Control"]
  node_management_http["Management API<br/>[handler.go]"]
  node_controller["Local Controller<br/>[controller.go]"]
  node_control_catalog["Function Catalog<br/>[catalog.go]"]
  node_control_release["Version Lifecycle<br/>[release.go]"]
  node_control_route["Route State<br/>[route.go]"]
  node_operations["Operation Records<br/>[operation.go]"]
end

subgraph group_admission["Artifact Admission"]
  node_artifact_store[("Artifact Store<br/>[store.go]")]
  node_validator_client["Validator Client<br/>[client.go]"]
  node_validator_process["Isolated Validator<br/>[main.go]"]
  node_validator_engine["Module Admission<br/>[engine.go]"]
end

subgraph group_serving["Serving and Routing"]
  node_serving_sync["Serving Projection<br/>[sync.go]"]
  node_discovery_builder["Discovery Builder<br/>[builder.go]"]
  node_discovery_store[("Gateway Discovery<br/>[store.go]")]
  node_gateway_http["Invocation HTTP<br/>[handler.go]"]
  node_gateway_invoke["Gateway Invocation<br/>[gateway.go]"]
  node_route_balancer["Route Balancer<br/>[balancer.go]"]
end

subgraph group_execution["Worker Execution"]
  node_worker_agent["Worker Agent<br/>[agent.go]"]
  node_worker_registry["Worker Registry<br/>[registry.go]"]
  node_worker_cache[("Compiled Cache<br/>[cache.go]")]
  node_wasm_engine["WASM Engine<br/>[engine.go]"]
end

subgraph group_composition["Local Core"]
  node_local_runtime["Process Composition<br/>[runtime.go]"]
end

node_admin(("Platform Operator"))
node_caller(("Function Caller"))

node_admin -->|"manages functions"| node_management_http
node_management_http -->|"dispatches writes"| node_controller
node_controller -->|"updates catalog"| node_control_catalog
node_controller -->|"records versions"| node_control_release
node_controller -->|"publishes routes"| node_control_route
node_controller -->|"tracks operations"| node_operations
node_controller -->|"stores artifacts"| node_artifact_store
node_controller -->|"requests validation"| node_validator_client
node_validator_client -->|"starts child"| node_validator_process
node_validator_process -->|"validates module"| node_validator_engine
node_controller -->|"updates serving state"| node_serving_sync
node_serving_sync -->|"builds view"| node_discovery_builder
node_serving_sync -->|"publishes view"| node_discovery_store
node_caller -->|"invokes function"| node_gateway_http
node_gateway_http -->|"reads serving view"| node_discovery_store
node_gateway_http -->|"dispatches invocation"| node_gateway_invoke
node_gateway_invoke -->|"selects worker"| node_route_balancer
node_gateway_invoke -->|"dispatches work"| node_worker_agent
node_worker_agent -->|"uses workers"| node_worker_registry
node_worker_agent -->|"loads program"| node_worker_cache
node_worker_agent -->|"executes module"| node_wasm_engine
node_local_runtime -->|"composes"| node_controller
node_local_runtime -->|"runs projection"| node_serving_sync
node_local_runtime -->|"hosts listener"| node_gateway_http
node_local_runtime -->|"hosts worker"| node_worker_agent

click node_management_http "https://github.com/yourikka/minicloud/blob/main/internal/managementhttp/handler.go"
click node_controller "https://github.com/yourikka/minicloud/blob/main/internal/localcontroller/controller.go"
click node_control_catalog "https://github.com/yourikka/minicloud/blob/main/internal/controlplane/catalog.go"
click node_control_release "https://github.com/yourikka/minicloud/blob/main/internal/controlplane/release.go"
click node_control_route "https://github.com/yourikka/minicloud/blob/main/internal/controlplane/route.go"
click node_operations "https://github.com/yourikka/minicloud/blob/main/internal/controlplane/operation.go"
click node_artifact_store "https://github.com/yourikka/minicloud/blob/main/internal/artifact/store.go"
click node_validator_client "https://github.com/yourikka/minicloud/blob/main/internal/validator/client.go"
click node_validator_process "https://github.com/yourikka/minicloud/blob/main/cmd/minicloud-validator/main.go"
click node_validator_engine "https://github.com/yourikka/minicloud/blob/main/internal/validator/engine/engine.go"
click node_serving_sync "https://github.com/yourikka/minicloud/blob/main/internal/localserving/sync.go"
click node_discovery_builder "https://github.com/yourikka/minicloud/blob/main/internal/discovery/builder.go"
click node_discovery_store "https://github.com/yourikka/minicloud/blob/main/internal/gatewaydiscovery/store.go"
click node_gateway_http "https://github.com/yourikka/minicloud/blob/main/internal/gatewayhttp/handler.go"
click node_gateway_invoke "https://github.com/yourikka/minicloud/blob/main/internal/gatewayinvoke/gateway.go"
click node_route_balancer "https://github.com/yourikka/minicloud/blob/main/internal/gatewayroute/balancer.go"
click node_worker_agent "https://github.com/yourikka/minicloud/blob/main/internal/workeragent/agent.go"
click node_worker_registry "https://github.com/yourikka/minicloud/blob/main/internal/workerregistry/registry.go"
click node_worker_cache "https://github.com/yourikka/minicloud/blob/main/internal/workercache/cache.go"
click node_wasm_engine "https://github.com/yourikka/minicloud/blob/main/internal/wasmexec/engine.go"
click node_local_runtime "https://github.com/yourikka/minicloud/blob/main/internal/localcore/runtime.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_management_http,node_controller,node_control_catalog,node_control_release,node_control_route,node_operations toneBlue
class node_artifact_store,node_validator_client,node_validator_process,node_validator_engine toneAmber
class node_serving_sync,node_discovery_builder,node_discovery_store,node_gateway_http,node_gateway_invoke,node_route_balancer toneMint
class node_worker_agent,node_worker_registry,node_worker_cache,node_wasm_engine toneRose
class node_local_runtime,node_admin,node_caller toneIndigo
```

## Components

### Management and Control

- [Management API](https://github.com/yourikka/minicloud/blob/main/internal/managementhttp/handler.go): `internal/managementhttp/handler.go`
- [Local Controller](https://github.com/yourikka/minicloud/blob/main/internal/localcontroller/controller.go): `internal/localcontroller/controller.go`
- [Function Catalog](https://github.com/yourikka/minicloud/blob/main/internal/controlplane/catalog.go): `internal/controlplane/catalog.go`
- [Version Lifecycle](https://github.com/yourikka/minicloud/blob/main/internal/controlplane/release.go): `internal/controlplane/release.go`
- [Route State](https://github.com/yourikka/minicloud/blob/main/internal/controlplane/route.go): `internal/controlplane/route.go`
- [Operation Records](https://github.com/yourikka/minicloud/blob/main/internal/controlplane/operation.go): `internal/controlplane/operation.go`

### Artifact Admission

- [Artifact Store](https://github.com/yourikka/minicloud/blob/main/internal/artifact/store.go): `internal/artifact/store.go`
- [Validator Client](https://github.com/yourikka/minicloud/blob/main/internal/validator/client.go): `internal/validator/client.go`
- [Isolated Validator](https://github.com/yourikka/minicloud/blob/main/cmd/minicloud-validator/main.go): `cmd/minicloud-validator/main.go`
- [Module Admission](https://github.com/yourikka/minicloud/blob/main/internal/validator/engine/engine.go): `internal/validator/engine/engine.go`

### Serving and Routing

- [Serving Projection](https://github.com/yourikka/minicloud/blob/main/internal/localserving/sync.go): `internal/localserving/sync.go`
- [Discovery Builder](https://github.com/yourikka/minicloud/blob/main/internal/discovery/builder.go): `internal/discovery/builder.go`
- [Gateway Discovery](https://github.com/yourikka/minicloud/blob/main/internal/gatewaydiscovery/store.go): `internal/gatewaydiscovery/store.go`
- [Invocation HTTP](https://github.com/yourikka/minicloud/blob/main/internal/gatewayhttp/handler.go): `internal/gatewayhttp/handler.go`
- [Gateway Invocation](https://github.com/yourikka/minicloud/blob/main/internal/gatewayinvoke/gateway.go): `internal/gatewayinvoke/gateway.go`
- [Route Balancer](https://github.com/yourikka/minicloud/blob/main/internal/gatewayroute/balancer.go): `internal/gatewayroute/balancer.go`

### Worker Execution

- [Worker Agent](https://github.com/yourikka/minicloud/blob/main/internal/workeragent/agent.go): `internal/workeragent/agent.go`
- [Worker Registry](https://github.com/yourikka/minicloud/blob/main/internal/workerregistry/registry.go): `internal/workerregistry/registry.go`
- [Compiled Cache](https://github.com/yourikka/minicloud/blob/main/internal/workercache/cache.go): `internal/workercache/cache.go`
- [WASM Engine](https://github.com/yourikka/minicloud/blob/main/internal/wasmexec/engine.go): `internal/wasmexec/engine.go`

### Local Core

- [Process Composition](https://github.com/yourikka/minicloud/blob/main/internal/localcore/runtime.go): `internal/localcore/runtime.go`

### Other components

- **Platform Operator**
- **Function Caller**

## Connections

- Platform Operator → Management API: manages functions
- Management API → Local Controller: dispatches writes
- Local Controller → Function Catalog: updates catalog
- Local Controller → Version Lifecycle: records versions
- Local Controller → Route State: publishes routes
- Local Controller → Operation Records: tracks operations
- Local Controller → Artifact Store: stores artifacts
- Local Controller → Validator Client: requests validation
- Validator Client → Isolated Validator: starts child
- Isolated Validator → Module Admission: validates module
- Local Controller → Serving Projection: updates serving state
- Serving Projection → Discovery Builder: builds view
- Serving Projection → Gateway Discovery: publishes view
- Function Caller → Invocation HTTP: invokes function
- Invocation HTTP → Gateway Discovery: reads serving view
- Invocation HTTP → Gateway Invocation: dispatches invocation
- Gateway Invocation → Route Balancer: selects worker
- Gateway Invocation → Worker Agent: dispatches work
- Worker Agent → Worker Registry: uses workers
- Worker Agent → Compiled Cache: loads program
- Worker Agent → WASM Engine: executes module
- Process Composition → Local Controller: composes
- Process Composition → Serving Projection: runs projection
- Process Composition → Invocation HTTP: hosts listener
- Process Composition → Worker Agent: hosts worker