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]|          |  |  |
|  |  |   +------+         +------+         +------+          |  |  |
|  |  |                                                       |  |  |
|  |  +-------------------------------------------------------+  |  |
|  +-------------------------------------------------------------+  |
+-------------------------------------------------------------------+
                                  |
                                  v
                   +-------------------------------+
                   |           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)
       |
       v
2. TinySignal CRD created
       |
       v
3. Signal Controller routes to node
       |
       v
4. Component.Handle() processes message
       |
       v
5. Output sent via handler callback
       |
       v
6. Edge expressions evaluate
       |
       v
7. Next node receives transformed data
       |
       v
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