smartbotic-microbit/docs/DEVELOPMENT.md

Development Guide

This guide covers setting up a development environment for Smartbotic Microbit and building the project from source.

Prerequisites

Operating System

• Linux (Debian 12+, Ubuntu 22.04+, or similar)
• macOS (with Homebrew) - experimental
• Windows WSL2 - experimental

Required Tools

Build Tools:

• CMake 3.20 or later
• C++20 compatible compiler:
  • GCC 11+ (recommended)
  • Clang 14+ (alternative)
• Make or Ninja build system
• Git with submodule support

Development Tools (recommended):

• clangd or ccls (LSP for IDE integration)
• gdb or lldb (debugging)
• valgrind (memory debugging)

System Dependencies

Debian/Ubuntu:

sudo apt update
sudo apt install -y \
    build-essential \
    cmake \
    git \
    pkg-config \
    libssl-dev \
    libcurl4-openssl-dev \
    libprotobuf-dev \
    protobuf-compiler \
    libgrpc++-dev \
    libspdlog-dev \
    nlohmann-json3-dev

Optional dependencies:

# For systemd integration
sudo apt install -y libsystemd-dev

# For development tools
sudo apt install -y clangd gdb valgrind

Node.js (for WebUI)

# Install Node.js 18+ (using NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify installation
node --version  # Should be v20.x or later
npm --version

Getting the Source Code

Clone the Repository

# Clone with submodules (important!)
git clone --recursive https://github.com/fszontagh/smartbotic-microbit.git
cd smartbotic-microbit

If you already cloned without --recursive:

git submodule update --init --recursive

Submodule Structure

The project includes the following submodule:

• external/smartbotic-database: Custom database service

Building the Backend

Configure with CMake

# Create build directory
mkdir build
cd build

# Configure (Release build)
cmake .. -DCMAKE_BUILD_TYPE=Release

# Or configure for Debug build with tests
cmake .. -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON

CMake Options:

Option	Default	Description
CMAKE_BUILD_TYPE	Release	Build type: Release, Debug, RelWithDebInfo
BUILD_TESTS	OFF	Build test suite
BUNDLE_DATABASE	OFF	Include database service in build
CMAKE_INSTALL_PREFIX	/usr/local	Installation prefix

Build

# Build with all CPU cores
make -j$(nproc)

# Or use ninja for faster builds
# cmake .. -GNinja
# ninja

Build artifacts:

build/
├── src/smartbotic-microbit           # Main executable
├── lib/                               # Compiled libraries
└── external/smartbotic-database/      # Database service (if BUNDLE_DATABASE=ON)

Run the Backend

# From the build directory
cd build

# Run with default config (from source tree)
./src/smartbotic-microbit --config ../config/microbit.json

# The server will start on http://localhost:8090

Environment Variables:

Set these before running for proper configuration:

export JWT_SECRET="your-secret-key-change-this"
export DB_ADDRESS="localhost:9004"
export SMTP_HOST=""  # Leave empty to disable email
export CALLERAI_API_URL="http://localhost:8080"
export CALLERAI_API_KEY=""
export WEBUI_PATH="../webui/dist"

Building the WebUI

Install Dependencies

cd webui
npm install

Development Server

# Start Vite dev server (with hot reload)
npm run dev

# The dev server will start on http://localhost:5173
# It proxies API requests to the backend

The dev server features:

• Hot module replacement (HMR)
• Fast refresh for React components
• TypeScript type checking
• Automatic browser reload

Build for Production

# Build optimized production bundle
npm run build

# Output will be in webui/dist/

Preview Production Build

npm run preview

Running the Complete Stack

Terminal 1: Database Service

# Build the database service
cd build
cmake .. -DBUNDLE_DATABASE=ON
make -j$(nproc)

# Run the database
cd external/smartbotic-database/src
./smartbotic-database --config ../../../../config/storage.json

Terminal 2: Backend Service

cd build
export JWT_SECRET="dev-secret-key"
export WEBUI_PATH="../webui/dist"
./src/smartbotic-microbit --config ../config/microbit.json

Terminal 3: WebUI Development Server

cd webui
npm run dev

Now access:

• WebUI: http://localhost:5173 (development) or http://localhost:8090 (production)
• API: http://localhost:8090/api/v1/*

Development Workflow

Code Style

C++ Code Style:

• Follow Google C++ Style Guide
• Use clang-format for formatting (config in .clang-format)
• Use meaningful variable and function names
• Add comments for complex logic

TypeScript/React:

• Use ESLint and Prettier (configs in webui)
• Functional components with hooks
• TypeScript strict mode enabled

Building Incrementally

After making changes:

# Backend
cd build
make -j$(nproc)

# WebUI (in dev mode, automatically rebuilds)
# Just save your files

Debugging

Backend Debugging with GDB:

# Build with debug symbols
cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j$(nproc)

# Run with debugger
gdb ./src/smartbotic-microbit
(gdb) run --config ../config/microbit.json

WebUI Debugging:

• Use browser DevTools
• React Developer Tools extension
• Source maps enabled in dev mode

Testing

Tests are currently under development. To enable test building:

cd build
cmake .. -DBUILD_TESTS=ON
make -j$(nproc)

# Run tests
ctest --output-on-failure

IDE Setup

Visual Studio Code

Recommended Extensions:

• C/C++ (Microsoft)
• clangd (LLVM)
• CMake Tools
• ESLint
• Prettier
• Tailwind CSS IntelliSense

Configuration (.vscode/settings.json):

{
  "cmake.buildDirectory": "${workspaceFolder}/build",
  "cmake.configureOnOpen": true,
  "clangd.arguments": [
    "--compile-commands-dir=${workspaceFolder}/build"
  ],
  "editor.formatOnSave": true,
  "C_Cpp.intelliSenseEngine": "disabled"
}

CLion

CLion has built-in CMake support:

1. Open the project root directory
2. CLion will automatically detect CMakeLists.txt
3. Configure build profiles in Settings → Build, Execution, Deployment → CMake

Common Development Tasks

Adding a New API Endpoint

1. Define the route handler in src/routes/{feature}_routes.cpp:

   void setupMyRoutes(httplib::Server& svr, App& app) {
   svr.Get("/api/v1/my-endpoint", [&app](const httplib::Request& req, httplib::Response& res) {
       // Handle request
   });
   }
   

2. Register routes in src/app.cpp:

   #include "routes/my_routes.hpp"
   
   void App::setupRoutes() {
   // ...
   setupMyRoutes(*httpServer_, *this);
   }
   

3. Rebuild:

   cd build && make
   

Adding a New Data Store

1. Create store files: src/stores/my_store.{hpp,cpp}
2. Define data model (struct with toJson(), fromJson())
3. Implement CRUD operations using database client
4. Add to App class in src/app.{hpp,cpp}

Modifying the Database Schema

1. Edit migration files in config/migrations/
2. Update store queries as needed
3. Restart database service to apply migrations

Adding a WebUI Page

1. Create page component in webui/src/pages/
2. Add route in webui/src/App.tsx
3. Create API client methods in webui/src/api/client.ts
4. Rebuild: Files auto-reload in dev mode

Troubleshooting

Build Issues

Problem: CMake can't find packages

# Make sure all dependencies are installed
sudo apt install -y libprotobuf-dev libgrpc++-dev libssl-dev libcurl4-openssl-dev

# Clear CMake cache
rm -rf build
mkdir build && cd build
cmake ..

Problem: Submodule errors

# Update submodules
git submodule update --init --recursive

Runtime Issues

Problem: Database connection failed

# Ensure database service is running
ps aux | grep smartbotic-database

# Check the port
netstat -tuln | grep 9004

Problem: WebUI can't connect to API

• Check CORS configuration in config/microbit.json
• Verify backend is running on port 8090
• Check browser console for errors

Problem: JWT errors

# Make sure JWT_SECRET is set
export JWT_SECRET="your-secret-key"

Performance Profiling

Using Valgrind

# Check for memory leaks
valgrind --leak-check=full ./src/smartbotic-microbit --config ../config/microbit.json

# Profile performance
valgrind --tool=callgrind ./src/smartbotic-microbit --config ../config/microbit.json
kcachegrind callgrind.out.*

Using perf

# Record performance
perf record -g ./src/smartbotic-microbit --config ../config/microbit.json

# View report
perf report

Code Coverage

# Build with coverage flags
cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="--coverage"
make -j$(nproc)

# Run tests
ctest

# Generate coverage report
lcov --capture --directory . --output-file coverage.info
genhtml coverage.info --output-directory coverage_html

Continuous Integration

The project can be integrated with CI/CD pipelines:

GitHub Actions Example:

name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive

      - name: Install dependencies
        run: |
          sudo apt update
          sudo apt install -y build-essential cmake libssl-dev \
            libcurl4-openssl-dev libprotobuf-dev protobuf-compiler \
            libgrpc++-dev libspdlog-dev nlohmann-json3-dev

      - name: Build
        run: |
          mkdir build && cd build
          cmake .. -DCMAKE_BUILD_TYPE=Release
          make -j$(nproc)

      - name: Test
        run: cd build && ctest --output-on-failure

Contributing

When contributing to the project:

1. Create a feature branch from main
2. Write clear commit messages
3. Follow the code style guidelines
4. Add tests for new features
5. Update documentation as needed
6. Submit a pull request for review

Additional Resources

• Architecture Documentation
• API Documentation
• Deployment Guide
• CMake Documentation
• gRPC C++ Guide
• React Documentation

Getting Help

• Issues: Report bugs on the GitHub issue tracker
• Questions: Contact the development team
• Email: support@smartbotics.ai