# 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:**

```bash
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:**

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

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

### Node.js (for WebUI)

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

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

If you already cloned without `--recursive`:

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

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

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

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

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

```bash
cd webui
npm install
```

### Development Server

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

```bash
# Build optimized production bundle
npm run build

# Output will be in webui/dist/
```

### Preview Production Build

```bash
npm run preview
```

## Running the Complete Stack

### Terminal 1: Database Service

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

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

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

```bash
# Backend
cd build
make -j$(nproc)

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

### Debugging

**Backend Debugging with GDB:**

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

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

```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`:

```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`:

```cpp
#include "routes/my_routes.hpp"

void App::setupRoutes() {
    // ...
    setupMyRoutes(*httpServer_, *this);
}
```

3. **Rebuild**:

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

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

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

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

## Performance Profiling

### Using Valgrind

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

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

# View report
perf report
```

## Code Coverage

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

```yaml
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](ARCHITECTURE.md)
- [API Documentation](API.md)
- [Deployment Guide](DEPLOYMENT.md)
- [CMake Documentation](https://cmake.org/documentation/)
- [gRPC C++ Guide](https://grpc.io/docs/languages/cpp/)
- [React Documentation](https://react.dev/)

## Getting Help

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