Core Concepts

Understanding these fundamental concepts will help you work effectively with TinySystems.

Visual Overview

┌─────────────────────────────────────────────────────────────────────┐
│                           WORKSPACE                                  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                         PROJECT                                │  │
│  │  ┌─────────────────────────────────────────────────────────┐  │  │
│  │  │                         FLOW                             │  │  │
│  │  │                                                          │  │  │
│  │  │    ┌──────┐         ┌──────┐         ┌──────┐           │  │  │
│  │  │    │ NODE │──EDGE──▶│ NODE │──EDGE──▶│ NODE │           │  │  │
│  │  │    │      │         │      │         │      │           │  │  │
│  │  │    │[PORT]│         │[PORT]│         │[PORT]│           │  │  │
│  │  │    └──────┘         └──────┘         └──────┘           │  │  │
│  │  │                                                          │  │  │
│  │  └─────────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │           CLUSTER             │
                    │  ┌─────────────────────────┐  │
                    │  │        MODULE           │  │
                    │  │  ┌───────────────────┐  │  │
                    │  │  │    COMPONENT      │  │  │
                    │  │  └───────────────────┘  │  │
                    │  └─────────────────────────┘  │
                    └───────────────────────────────┘

Glossary

Flow

A Flow is a visual workflow consisting of connected nodes. Flows define the logic of your automation or data pipeline.

• Flows are designed in the visual editor
• Each flow belongs to a project
• Flows can be versioned with automatic revisions
• Deployed flows create TinyNode CRDs in Kubernetes

Node

A Node is an instance of a component within a flow. Each node:

• Represents a running instance of a component
• Has configurable input and output ports
• Stores its configuration in a TinyNode CRD
• Can be connected to other nodes via edges

Edge

An Edge is a connection between two nodes that defines how data flows:

• Connects an output port of one node to an input port of another
• Contains expressions for data transformation
• Supports type mapping between different schemas

Port

A Port is an input or output endpoint on a node:

• Input ports (left side) receive data
• Output ports (right side) emit data
• Each port has a typed schema (JSON Schema)
• Ports define what data a component accepts and produces

Component

A Component is the code that defines a node's behavior:

• Implements the Component interface in Go
• Defines available ports and their schemas
• Contains the Handle function for processing messages
• Multiple nodes can use the same component

Module

A Module is a packaged collection of related components:

• Deployed as a Kubernetes operator
• Contains one or more components
• Runs as pods in your cluster
• Examples: common-module, http-module

Expression

An Expression is a data transformation syntax used in edges:

{{$.request.body.userId}}     // JSONPath access
{{$.count + 1}}               // Arithmetic
{{'Hello ' + $.name}}         // String concatenation

• Expressions use Mustache-style {{}} delimiters
• Support JSONPath for accessing nested data
• Can include operators and functions

Project

A Project is a container for related flows:

• Groups flows by purpose or application
• Contains project-level settings
• Supports dashboards for monitoring

Workspace

A Workspace provides multi-tenant isolation:

• Each workspace has its own projects and flows
• Users can be members of multiple workspaces
• Access control is workspace-scoped

Cluster

A Cluster is a Kubernetes cluster connected to the platform:

• Runs module operators
• Executes flow nodes
• Can be managed or self-hosted
• Multiple clusters can be connected

Data Flow

When a flow executes, data moves through the system like this:

1. Trigger (HTTP request, signal, timer)
       │
       ▼
2. TinySignal CRD created
       │
       ▼
3. Signal Controller routes to node
       │
       ▼
4. Component.Handle() processes message
       │
       ▼
5. Output sent via handler callback
       │
       ▼
6. Edge expressions evaluate
       │
       ▼
7. Next node receives transformed data
       │
       ▼
8. Repeat until flow completes

Kubernetes Resources

TinySystems uses Custom Resource Definitions (CRDs) to represent flows in Kubernetes:

CRD	Purpose
TinyNode	Represents a node instance with configuration
TinyModule	Registers a module and its components
TinySignal	Triggers execution of a node's port
TinyFlow	Groups nodes belonging to a flow
TinyProject	Top-level project container

Next Steps

• Architecture Overview - Understand the system architecture
• Quick Start - Build your first flow