Backend Module

Backend Module

ION Flow Backend - Full-featured backend with WebSocket support, authentication, and multi-tenancy.

---

Overview

The Backend module (backend/) extends the Core engine with enterprise features:

• Real-time Execution - WebSocket-based flow monitoring and control
• Authentication - JWT and OAuth2 support
• Multi-tenancy - Isolated data per company/tenant
• Scheduled Execution - Cron-based flow scheduling
• Version Control - Git-based flow versioning

---

Module Structure

backend/
├── backend.go              # Entry point
├── ion/
│   ├── board/              # WebSocket execution engine
│   ├── controllers/        # REST API controllers
│   ├── services/           # Business logic
│   ├── models/             # Backend-specific models
│   ├── nodes/              # Platform-specific nodes
│   ├── params/             # DTOs for controllers
│   ├── helpers/            # Backend utilities
│   ├── middleware/         # HTTP middleware
│   ├── database/           # Database connections
│   ├── scheduler/          # Cron scheduling
│   └── workspace/          # Flow workspace management
└── routes/
    ├── api.go              # REST API routes
    └── channels.go         # WebSocket routes

---

Key Features

Board Engine

Real-time flow execution with WebSocket communication:

engine := board.NewExecutionEngine(sessionID, executor, context, messageSender)
engine.Start()   // Begin execution
engine.Pause()   // Pause execution
engine.Resume()  // Resume execution
engine.Stop()    // Stop execution

Learn more about Board

API Routes

Two main route groups:

Prefix	Auth	Description
/api/2.0/webcomponent	WebComponent Auth	Public app endpoints
/api/1.0/tenants/{tenantId}	JWT + Tenant Auth	Tenant-specific endpoints

Learn more about Routes

Database Connections

Two connection patterns:

// Global (Account level)
database.GetConnection().Model(&model).First(&result)

// Tenant (Company level)
company.CompanySchema(models.TableName()).First(&result)

Learn more about Database

---

Startup Process

func Up() {
    // 1. Load environment
    godotenv.Load()

    // 2. Connect database
    database.Connect()

    // 3. Set SQLite path for flows
    db.DB_PATH = "./storage/dbs"

    // 4. Initialize scheduler
    scheduleManager := scheduler.NewScheduleManager()
    scheduler.StartTaskScheduler(cr, scheduleManager)

    // 5. Setup routes
    routes.ApiRouters(r)
    routes.ChannelsRouters(r)

    // 6. Setup WebSocket
    board.SetupWebSocket()
    board.SetupHub()

    // 7. Load auth keys
    middleware.LoadPublicKey("./storage/oauth-public.key")

    // 8. Start server
    http.ListenAndServe(port, handler)
}

---

Execution Modes

Development Mode

Real-time debugging with WebSocket feedback:

• Step-by-step execution
• Progress messages for each node
• Pause/Resume/Stop controls
• Input waiting capabilities

Live Mode

Background execution without WebSocket:

• Creates execution records
• Handles app nodes
• Persists execution state
• No real-time feedback

---

Controllers

Organized by route group:

Group	Controllers	Purpose
WebComponent	Connection, Flow, Integration	Public app endpoints
Tenant	Flow, Connection, App, Webhook	Company endpoints
Account	Flow, Intent, Webhook	Account endpoints

Learn more about Controllers

---

Services

Business logic services:

Service	File	Purpose
CompanyFlowService	company_flow_service.go	Company flow CRUD
AccountFlowService	account_flow_service.go	Account flow CRUD
CompanyWebhookService	company_webhook_service.go	Webhook management
ScheduleService	schedule_service.go	Cron scheduling
AttemptService	attempt_service.go	Connection attempts

Learn more about Services

---

Dependencies

Library	Purpose
github.com/gorilla/mux	HTTP routing
github.com/gorilla/websocket	WebSocket support
github.com/golang-jwt/jwt/v5	JWT authentication
github.com/robfig/cron/v3	Cron scheduling
github.com/go-git/go-git/v6	Git operations
gorm.io/gorm	Database ORM
gorm.io/driver/postgres	PostgreSQL driver

---

Environment Variables

Variable	Description
PORT	Server port
DATABASE_URL	PostgreSQL connection string
ENVIRONMENT	”production” or “development”
JWT_PUBLIC_KEY	Path to JWT public key

---

Related Documentation

• Board Engine - WebSocket execution
• Routes - API endpoints
• Controllers - Request handlers
• Services - Business logic
• Database - Connection patterns