# 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
```bash
# 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/)
```bash
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:

```bash
# 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

1. **Database Service** (src/database/) - gRPC storage server with in-memory store, WAL persistence, and snapshots
2. **WebServer Service** (src/webserver/) - HTTP REST API, WebSocket for real-time updates, JWT auth, runner registry
3. **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:
```javascript
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](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:

```bash
# 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