CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SmartBotic is a workflow automation and execution platform with a microservices architecture. The backend is C++20 with gRPC communication, and the frontend is React/TypeScript.

Build Commands

C++ Backend

# Debug build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make

# Release build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

# With Address Sanitizer
cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ASAN=ON ..
make

Frontend (webui/)

cd webui
npm install
npm run dev      # Dev server (port 3000, proxies to localhost:8090)
npm run build    # Production build
npm run lint     # ESLint

Running Services

Services must start in order due to dependencies:

# 1. Database service first (gRPC port 9010)
./build/smartbotic-database

# 2. WebServer (HTTP port 8090, gRPC port 9002)
./build/smartbotic-webserver

# 3. Runner(s) (gRPC port 9011)
./build/smartbotic-runner

# Or use systemd
systemctl --user start smartbotic.target
journalctl --user -u smartbotic-* -f

Architecture

Three Microservices

Database Service (src/database/) - gRPC storage server with in-memory store, WAL persistence, and snapshots
WebServer Service (src/webserver/) - HTTP REST API, WebSocket for real-time updates, JWT auth, runner registry
Runner Service (src/runner/) - Workflow execution engine with QuickJS for JavaScript node evaluation

Data Flow

WebUI (React) → HTTP/WebSocket → WebServer → gRPC → Database
                                     ↓
                              gRPC → Runner(s) → executes workflows

Key Directories

lib/ - Shared libraries (common utilities, config loader, logging, storage client)
proto/ - Protocol Buffer definitions for gRPC services
src/ - Microservice implementations
nodes/ - Built-in workflow node definitions (JavaScript modules)
webui/ - React frontend
config/ - Runtime JSON configuration files

Node System

Workflow nodes are JavaScript modules in nodes/ with this interface:

module.exports = {
  configSchema: { /* JSON Schema */ },
  inputSchema: { /* JSON Schema */ },
  outputSchema: { /* JSON Schema */ },
  execute: async (config, input, context) => { /* returns output */ }
}

Nodes are loaded by the Runner service and executed in QuickJS. Hot-reload is supported.

See docs/nodes.md for complete node creation guide.

Migrating Nodes to Database

After creating or modifying nodes in nodes/, migrate them to the running database:

# 1. Login to get JWT token
TOKEN=$(curl -s http://localhost:8090/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}' | jq -r '.accessToken')

# 2. Migrate nodes from filesystem to database
curl -X POST http://localhost:8090/api/v1/nodes/migrate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nodesPath": "./nodes"}'

# 3. Verify nodes are loaded
curl -s http://localhost:8090/api/v1/nodes \
  -H "Authorization: Bearer $TOKEN" | jq '.nodes[] | "\(.id) - \(.name)"'

Runners automatically receive node updates via gRPC streaming - no restart required.

Configuration

Services load JSON configs from config/ directory:

database.json - Storage settings, WAL/snapshot intervals
webserver.json - HTTP port, JWT settings, runner load balancing
runner.json - Runner ID, max concurrent executions, hot reload settings

Environment variables can override config values using ${VAR_NAME:default} syntax.

C++ Standards

C++20 required (strict compliance, no extensions)
Compiler warnings: Wall, Wextra, Wpedantic
Key libraries: gRPC, Protobuf, cpp-httplib, QuickJS, spdlog, nlohmann/json, bcrypt

Frontend Stack

React 18.2 + TypeScript + Vite
State: Zustand + React Query
UI: TailwindCSS + Lucide icons
Workflow editor: ReactFlow

CLAUDE.md 4.0 KB Lịch sử Raw