Glossary

Definitions of key terms used throughout the TinySystems documentation.

A

Aggregator

A component that collects multiple messages and combines them into a single output, typically used for fan-in patterns or collecting parallel results.

API Server

The Kubernetes API server that manages cluster state. TinySystems components interact with it through the controller to manage CRDs.

B

Blocking Execution

TinySystems' execution model where the output() handler blocks until all downstream processing completes, returning a module.Result. This ensures reliable message delivery and backpressure handling.

Branch

A flow path that diverges from a main path, typically created by router components with multiple output ports.

Bundle

A curated third-party subchart (e.g. tei, pgvector) carried by the shared operator chart, which a module can request via the SDK's module.Bundle and an installer enables per install (tiny install <module> --bundle <alias>).

C

Component

A reusable building block in TinySystems that implements specific functionality. Components define ports, handle messages, and can be configured via settings. Implemented as Go structs satisfying the module.Component interface and registered via registry.Register.

Component Info

Metadata about a component: Name, Description, Info, and Tags. Returned by the GetInfo() method, and published in a module repo's components.yaml for pre-install discovery.

Control Port

A system port (_control) that handles UI interactions like button clicks. Components handle it by implementing ControlHandler (OnControl).

Controller

The Kubernetes operator embedded in every module binary (run) that watches TinyNode resources and coordinates message delivery between components.

CR (Custom Resource)

A Kubernetes API extension that stores custom data. TinySystems uses TinyModule, TinyNode, and TinyFlow CRs.

CRD (Custom Resource Definition)

The schema that defines a Custom Resource type in Kubernetes. Installed by tiny up.

D

Data Mapping

The process of transforming data from one structure to another using expressions in edge configurations.

Downstream

Components or nodes that receive output from the current component. In flow terms, components to the right or below.

E

Edge

A connection between two ports that defines data flow and transformation. Configured in TinyNode.spec.edges.

Edge Data

The configuration attached to an edge that specifies how data is transformed as it flows between ports.

Error Message

The canonical payload of an error port: module.ErrorMessage with {context, error, retryable}, built with module.NewError. The retry component and the platform rely on this shape.

Expression

A template syntax (double curly braces like { {...} }) used in edge configurations for dynamic data transformation. Supports path access, operators, and functions.

Expression Evaluator

The runtime component that parses and executes expressions, transforming input data according to expression rules.

F

Fan-In

A pattern where multiple flow paths converge into a single component.

Fan-Out

A pattern where a single component's output is sent to multiple downstream components.

Flow

A directed graph of connected nodes that defines data processing logic. Represented as a collection of TinyNode resources grouped by a TinyFlow.

Flow Editor

The visual interface for creating and editing flows, displaying nodes, edges, and configurations. Served locally by the tiny dev server.

G

GetInfo()

Component interface method that returns the component's metadata (module.ComponentInfo: name, description, info, tags).

gRPC

The default protocol for communication between different module pods (the chart binds it on :8483). Cross-module messages can alternatively travel over NATS when TINY_NATS_URL is set.

H

Handle()

The main component interface method that processes incoming messages. Receives context, output handler, port name, and message; returns a module.Result (built with module.Ok / module.Fail).

Handler

The function type func(ctx context.Context, port string, data any) module.Result used to send output messages from components. Its return must be chained up the call stack so blocking I/O responses propagate.

Helm Chart

Modules do not have their own charts. Every module deploys with the shared tinysystems/tinysystems-operator chart (from https://tiny-systems.github.io/module/), parameterized by the module's image and a values overlay.

I

Index (Module Index)

The static index.yaml of a module repo, generated with tiny repo index from per-module module.yaml (and components.yaml) files. What tiny install and the platform resolve modules and versions from.

Ingress

A Kubernetes resource that manages external HTTP access to services. Created by the SDK's resource manager when a component exposes a port.

Identity Port

A system port (_identity) through which the framework tells a component which node it is. Components implement IdentityAware (OnIdentity) — or embed module.Base — to receive it.

Input Port

A port that receives messages (Source: false). Conventionally placed on the left side of nodes in the flow editor (Position: module.Left).

Instance()

Component interface method that returns a new instance of the component. Used by the runtime to create a fresh instance per node.

J

JSON Schema

The schema format automatically generated from Go structs (via reflection on a port's Configuration) to define port message structures and UI rendering. A port can instead publish a runtime-authored schema verbatim via Port.Schema.

K

Kubernetes Lease

A Kubernetes resource used for leader election. Each module deployment holds one Lease (<module>-lock) — leadership is per module, not per node.

L

Leader

The pod of a module deployment that holds the module's Lease. The leader performs status updates and leader-only component work (timers, cron, server singleton duties).

Leader-Reader Pattern

An architecture where the leader pod handles state modifications and singleton work while all pods process messages. Used for scalability.

M

Message

Data passed between components through ports. Messages are typed according to port configurations.

Metadata

Key-value pairs stored in TinyNode.Status.Metadata for sharing state across replicas. Accessed through module.State (leader writes, all pods read via the watch).

Module

A container image that bundles related components. Deployed by the shared operator chart as a Kubernetes Deployment whose entrypoint is the module binary's run command.

Module Discovery

How modules become known: a running module registers a TinyModule CR (with live component/port introspection in its status), and installable modules are listed in repo indexes (components.yaml provides pre-install component info).

Module Repo

A static, Helm-style repository of installable modules: per-module module.yaml manifests and a generated index.yaml, hosted as plain files. Managed on the consumer side with tiny repo add/update/list/remove.

N

Namespace

A Kubernetes namespace where TinyNode resources and module pods are deployed (default tinysystems). Must be labeled tinysystems.io/managed=true; the pre-install hook enforces this.

Node

A visual representation of a component instance in the flow editor. Corresponds to a TinyNode resource.

O

Output Handler

The module.Handler passed to Handle() (and injected long-lived via EmitterAware) for sending messages to output ports. Returns module.Result.

Output Port

A port that emits messages (Source: true). Conventionally placed on the right side of nodes in the flow editor (Position: module.Right).

P

Pod

A Kubernetes pod running a module. Multiple pods can run for the same module for scalability.

Port

A named connection point on a component for receiving or sending messages. Defined in the Ports() method as module.Port.

Port Position

The visual placement of a port on a node: module.Top, module.Right, module.Bottom, or module.Left.

R

Reader

A non-leader pod of a module deployment. Processes messages but skips leader-only work; observes shared state via the TinyNode watch.

Reconcile

The Kubernetes controller loop that ensures actual state matches desired state. Components react to it by implementing ReconcileHandler (OnReconcile).

Reconcile Port

A system port (_reconcile) that carries TinyNode updates during reconciliation. Used for state restoration and propagation.

Resource Manager

The SDK facility that creates and maintains Kubernetes resources (Services, Ingresses) on a component's behalf, e.g. when a port is exposed.

Result

module.Result — the typed return of Handle and every handler call. Wraps a payload or an error; constructed with module.Ok / module.Fail, read with Err() / Value().

Retryable

An error marked with module.Retryable(err) to signal a transient failure. Only marked-retryable failures are re-attempted (by edges and the retry component alike, via module.ShouldRetry); unmarked errors are never retried.

Router

A component that directs messages to different output ports based on conditions.

S

Schema

The JSON Schema representation of a port's message shape, used for UI generation and validation. Reflected from the Go type by default, or supplied verbatim via Port.Schema for runtime-authored forms.

Secret

A Kubernetes resource for storing sensitive data. Referenced in node settings with a [[secret:<name>/<key>]] placeholder, resolved by the SDK at dispatch time (requires secrets.enabled: true in the module's install values).

Service

A Kubernetes Service that exposes module pods for network access. Created for gRPC endpoints and exposed HTTP ports.

Settings

Component configuration provided via the _settings port. Defined as a Go struct with struct tags; delivered to OnSettings (SettingsHandler).

Settings Port

A system port (_settings) that carries component configuration when nodes are created or updated.

Signal

A manual trigger sent into a running flow via the MCP send_signal tool (served by the tiny dev server). There is no TinySignal CR.

Source Port

A port with Source: true — the port is a source of data, i.e. an output port. Source: false ports receive input.

State

module.State — the SDK storage primitive (Get/Set/Delete/List, plus Scoped for execution-scope durable state). Backed by TinyNode metadata by default, JetStream KV for execution scope.

Struct Tags

Go struct field annotations that control JSON Schema generation and UI rendering (e.g. json, title, description, required, configurable).

System Port

A built-in port for platform infrastructure. There are five: _settings, _control, _reconcile, _client, and _identity. Modern components handle them through capability interfaces (OnSettings, OnControl, OnReconcile, OnClient, OnIdentity) rather than switching on port names.

T

TinyFlow

A CR that groups the TinyNodes of one flow.

TinyModule

A CR that a running module registers, carrying its name, version, SDK version, address, and introspected components in status.

TinyNode

The primary CR representing a component instance. Contains the component reference and edges in spec; module/component/ports introspection, a free-form status string, and an error flag in status (there is no .status.state field).

Transformation

The process of converting data from input format to output format using expressions.

U

Upstream

Components or nodes that send messages to the current component. In flow terms, components to the left or above.

W

Webhook

An HTTP endpoint that receives events from external systems. Implemented using HTTP server components.

Workspace

An organizational unit on the platform that groups related flows and resources. Workspaces register their own module repos, which feed their module catalogs.

Acronyms