SDK Installation

The TinySystems SDK provides everything you need to build custom modules and components.

Installation

Create a New Module

# Create project directory
mkdir my-module && cd my-module

# Initialize Go module
go mod init github.com/myorg/my-module

# Install the SDK
go get github.com/tiny-systems/module@latest

Verify Installation

go list -m github.com/tiny-systems/module
# github.com/tiny-systems/module v0.1.x

SDK Package Overview

The SDK is organized into several packages:

Package	Import Path	Purpose
module	github.com/tiny-systems/module/module	Core interfaces (Component, Port, Handler)
registry	github.com/tiny-systems/module/registry	Component registration
cli	github.com/tiny-systems/module/cli	CLI commands (run, build, tools)
v1alpha1	github.com/tiny-systems/module/api/v1alpha1	CRD types (TinyNode, TinyModule)
resource	github.com/tiny-systems/module/pkg/resource	Kubernetes resource manager
evaluator	github.com/tiny-systems/module/pkg/evaluator	Expression evaluation
schema	github.com/tiny-systems/module/pkg/schema	JSON Schema generation
errors	github.com/tiny-systems/module/pkg/errors	Error handling utilities

Core Interfaces

Component Interface

The main interface you'll implement:

import "github.com/tiny-systems/module/module"

type Component interface {
    // Returns component metadata (name, description, tags)
    GetInfo() ComponentInfo

    // Processes incoming messages on ports
    Handle(ctx context.Context, output Handler, port string, message any) any

    // Defines input and output ports
    Ports() []Port

    // Factory method to create new instances
    Instance() Component
}

Handler Function

The callback for sending output:

type Handler func(ctx context.Context, port string, data any) any

Port Definition

Define component ports:

type Port struct {
    Name          string      // Unique identifier
    Label         string      // Display name in UI
    Position      Position    // Left, Right, Top, Bottom
    Source        bool        // true = output port
    Configuration interface{} // Schema definition struct
}

Minimal Example

Here's a complete minimal module:

// cmd/main.go
package main

import (
    "context"

    "github.com/tiny-systems/module/cli"
    "github.com/tiny-systems/module/module"
    "github.com/tiny-systems/module/registry"
)

// Component implementation
type Echo struct{}

func (e *Echo) GetInfo() module.ComponentInfo {
    return module.ComponentInfo{
        Name:        "echo",
        Description: "Echoes input to output",
    }
}

func (e *Echo) Handle(ctx context.Context, output module.Handler, port string, msg any) any {
    return output(ctx, "output", msg)
}

func (e *Echo) Ports() []module.Port {
    return []module.Port{
        {Name: "input", Label: "Input", Position: module.Left},
        {Name: "output", Label: "Output", Position: module.Right, Source: true},
    }
}

func (e *Echo) Instance() module.Component {
    return &Echo{}
}

func init() {
    registry.Register(&Echo{})
}

func main() {
    cli.Run()
}

Running Your Module

Local Development

# Build the module
go build -o my-module ./cmd

# Run locally (connects to current kubectl context)
./my-module run \
    --name=my-module \
    --version=1.0.0 \
    --namespace=default

With Environment Variables

# Enable OpenTelemetry tracing
OTLP_DSN=http://localhost:4317 ./my-module run \
    --name=my-module \
    --version=1.0.0 \
    --namespace=default

Available CLI Commands

The SDK includes a CLI with these commands:

# Run the module operator
./my-module run --help

# Build and publish
./my-module tools build --help

# Show component info
./my-module tools info

See CLI Reference for details.

Dependencies

The SDK brings in these key dependencies:

require (
    // Kubernetes
    sigs.k8s.io/controller-runtime
    k8s.io/client-go
    k8s.io/apimachinery

    // gRPC (cross-module communication)
    google.golang.org/grpc

    // OpenTelemetry (observability)
    go.opentelemetry.io/otel

    // Expression evaluation
    github.com/spyzhov/ajson
)

Next Steps

• Hello World Component - Build a complete component
• Project Structure - Organize your module
• Component Interface - Deep dive into the API