Development Guide

Development Guide

Setting up your development environment - Complete guide for ION Flow development.

---

Prerequisites

Requirement	Version	Purpose
Go	1.24.3+	Primary language
PostgreSQL	14+	Backend database
SQLite3	3.x	Flow workspace storage
Git	2.x	Version control

---

Initial Setup

1. Clone Repository

git clone https://gitlab.com/altacrest/flow_binaries.git
cd flow_binaries

2. Install Dependencies

# Root module
go mod download

# Core module
cd core && go mod download && cd ..

# Backend module
cd backend && go mod download && cd ..

# Server module
cd server && go mod download && cd ..

# Packages
cd packages/channel && go mod download && cd ../..
cd packages/helpers && go mod download && cd ../..

3. Environment Setup

Create .env file in project root:

# Server
PORT=8000

# Database
DATABASE_URL=postgres://user:password@localhost:5432/ion_flow?sslmode=disable

# Environment
ENVIRONMENT=development

# Storage
FLOW_DB_PATH=./storage/dbs
STORE_DB_PATH=./storage/store
REPO_PATH=./storage/repos

4. Database Setup

# Create database
createdb ion_flow

# Run migrations (if applicable)
# Migrations are handled by GORM auto-migrate

5. Create Storage Directories

mkdir -p storage/dbs
mkdir -p storage/store
mkdir -p storage/repos

---

Running the Application

Backend (Full)

# From project root
go run main.go

# Or with air for hot reload
air

Server (Microservice)

cd server
go run . -port 8080 -path ../storage/dbs

Running Tests

# All tests
go test ./...

# Core tests
cd core && go test ./...

# Backend tests
cd backend && go test ./...

# With coverage
go test -cover ./...

---

Project Structure

ion-binaries/
├── main.go           # Entry point (runs backend)
├── go.mod            # Root module
├── core/             # Flow engine (heart)
├── backend/          # Full backend with WebSocket
├── server/           # REST microservice
├── packages/         # Reusable packages
│   ├── channel/      # Auth engine
│   └── helpers/      # Utilities
├── cli/              # DEPRECATED
├── storage/          # Runtime data (gitignored)
└── docs/             # Documentation

---

Module Dependencies

graph TD
    Main[main.go] --> Backend
    Backend --> Core
    Backend --> Channel[packages/channel]
    Backend --> Helpers[packages/helpers]
    Server --> Core
    Channel --> Core
    Channel --> Helpers

Replace Directives

Go modules use replace directives for local development:

// In backend/go.mod
replace gitlab.com/altacrest/flow_binaries/core => ../core
replace gitlab.com/altacrest/flow_binaries/packages/helpers => ../packages/helpers
replace gitlab.com/altacrest/flow_binaries/packages/channel => ../packages/channel

---

Code Style

Naming Conventions

Item	Convention	Example
Package	lowercase	services, models
Exported	PascalCase	GetFlow, UserModel
Unexported	camelCase	findNode, parseData
Constants	PascalCase	StatusSuccess

File Organization

package services

import (
    "standard library"

    "external packages"

    "internal packages"
)

// Constants
const (...)

// Types
type Service struct {...}

// Constructor
func NewService() *Service {...}

// Methods
func (s *Service) DoSomething() {...}

// Private helpers
func helperFunc() {...}

Comments

• All comments in English
• Document exported functions
• Explain non-obvious logic

// GetFlow retrieves a flow by ID from the company's schema.
// Returns nil if not found without error.
func GetFlow(company *models.Company, flowId uint) (*models.Flow, error) {
    // Check company context
    if company == nil {
        return nil, errors.New("company is required")
    }
    // ...
}

---

Adding New Features

New Node Type (Core)

1. Create directory: core/actions/mynewnode/
2. Implement Execute function
3. Add tests
4. Document in docs/core/actions/

New Backend Feature

1. Add model if needed: backend/ion/models/
2. Add service: backend/ion/services/
3. Add controller: backend/ion/controllers/
4. Add route: backend/routes/api.go
5. Add params (DTO): backend/ion/params/
6. Document in docs/backend/

New Generic Utility

1. Check if it exists in packages/helpers/
2. If generic: add to packages/helpers/
3. If core-specific: add to core/helpers/
4. If backend-specific: add to backend/ion/helpers/

---

Debugging

Logging

import "log"

log.Println("Debug message")
log.Printf("Value: %v", variable)

SQLite Inspection

sqlite3 storage/dbs/flow-123.db
.tables
SELECT * FROM nodes;
SELECT * FROM queue;

WebSocket Testing

Use wscat or browser dev tools:

wscat -c ws://localhost:8000/tenant/123/ws

---

IDE Setup

VS Code

Recommended extensions:

• Go (golang.go)
• GitLens
• Better Comments

Cursor

Same as VS Code, plus:

• Use workspace rules from .cursor/rules/

---

Related Documentation

• Testing Guide - Testing practices
• Building Guide - Build process
• Architecture - System overview