ION Flow Documentation

ION Flow Documentation

Comprehensive developer documentation for the ION Flow workflow automation system

---

Welcome

ION Flow is a modular workflow automation system built in Go that enables visual flow creation, execution, and real-time monitoring. This documentation provides complete technical reference for developers working with the ION Flow ecosystem.

---

Quick Navigation

Core Modules

Module	Description	Link
Core Engine	The heart of flow execution - processes nodes, manages state	View Documentation
Backend	Full-featured backend with WebSocket, authentication, multi-tenancy	View Documentation
Server	REST microservice exposing core APIs	View Documentation
Packages	Reusable portable modules (channel, helpers)	View Documentation

Getting Started

Guide	Description
Architecture Overview	System architecture, module dependencies, technology stack
Development Guide	Setting up development environment
Testing Guide	Running and writing tests
Building Guide	Building and compiling the project
Deployment Guide	Deploying ION Flow

---

System Overview

graph TB
    subgraph Client [Client Applications]
        WebApp[Web Application]
        BunJS[Bun/JavaScript]
        PHP[PHP Integration]
    end

    subgraph ION [ION Flow System]
        Backend[Backend - WebSocket + REST]
        Server[Server - REST Microservice]
        Core[Core - Flow Engine]
        Channel[Channel - Auth Package]
    end

    subgraph Storage [Data Storage]
        PostgreSQL[(PostgreSQL)]
        SQLite[(SQLite)]
    end

    WebApp --> Backend
    BunJS --> Server
    PHP --> Server

    Backend --> Core
    Backend --> Channel
    Server --> Core

    Backend --> PostgreSQL
    Core --> SQLite

---

Module Architecture

Core Engine (core/)

The heart of ION Flow - responsible for:

• Flow execution and state management
• Node processing and data transformation
• Queue/Stack-based execution model
• SQLite workspace persistence

Key APIs:

flow.LoadFlow(flowId, flow)      // Initialize flow workspace
flow.RunNode(flowId, nodeId)     // Start node execution
flow.PushNode(flowId, ots, ...)  // Push results, continue flow
flow.ContinueNode(flowId)        // Get next node from queue

Learn more about Core

---

Backend (backend/)

The main ION Flow backend extending core with:

• WebSocket-based real-time execution monitoring
• JWT authentication and authorization
• Multi-tenant data isolation
• Scheduled flow execution (cron)
• Git-based flow version control

Key Features:

• Development and Live execution modes
• Real-time progress streaming
• Pause/Resume/Stop controls
• Input waiting capabilities

Learn more about Backend

---

Server (server/)

A lightweight REST microservice that exposes core flow APIs:

• Used by external applications (Bun, PHP)
• Stateless flow execution
• Data store management

Endpoints:

POST /load       - Load flow into workspace
POST /run        - Run initial node
POST /continue   - Continue to next node
POST /push       - Push node results
POST /mapper     - Execute mapper

Learn more about Server

---

Packages (packages/)

Reusable, portable modules:

Channel (packages/channel/)

Authentication engine supporting:

• OAuth 2.0 (Authorization Code, Client Credentials)
• API Key authentication
• Basic authentication
• Token refresh handling

Helpers (packages/helpers/)

Generic utilities:

• Configuration parsing
• JSONC sanitization
• Pointer helpers

Learn more about Packages

---

Technology Stack

Category	Technology	Purpose
Language	Go 1.24.3	Primary development language
HTTP Router	Gorilla Mux	REST API routing
WebSocket	Gorilla WebSocket	Real-time communication
ORM	GORM	Database abstraction
Databases	PostgreSQL, SQLite	Data persistence
Expression	expr-lang/expr	Dynamic parameter evaluation
Auth	JWT	Token-based authentication
Scheduling	robfig/cron	Scheduled flow execution

---

Documentation Standards

This documentation follows:

• IEEE 830-1998 - Software Requirements Specification
• IEEE 26514-2010 - Systems and Software Engineering — User Documentation

Each section includes:

1. Overview and purpose
2. Technical specifications
3. API reference with signatures
4. Code examples
5. Cross-references to related documentation

---

Quick Links

By Role

New Developers:

1. Architecture Overview
2. Development Guide
3. Core Engine Basics

Backend Developers:

1. Backend Architecture
2. Board Engine
3. Database Connections

Integration Developers:

1. Server REST API
2. Channel Authentication
3. WebSocket Channels

---

Contributing

Adding New Features

Feature Type	Location	Documentation
New node type	core/actions/	/docs/core/actions/
Backend feature	backend/ion/	/docs/backend/
REST endpoint	server/	/docs/server/
Generic utility	packages/helpers/	/docs/packages/helpers/
Auth pattern	packages/channel/	/docs/packages/channel/

Code Guidelines

• All comments in English
• All documentation in English
• Follow Go naming conventions
• Write tests for all core actions
• Check existing helpers before creating new ones

---

Version History

See Changelog for version history and release notes.

---

Support

• Repository: GitLab - flow_binaries
• Maintainers: [email protected]