# Smartbotic Microbit

## What is this?

Smartbotic Microbit is a **self-service admin/management platform on top of the CallerAI telephony AI engine**.

The goal: small and medium businesses (hair salons, medical offices, auto repair shops, etc.) can set up an **AI phone assistant** through a web interface in a few clicks — one that answers calls, responds to questions, and **books appointments** — without needing to deal with APIs directly.

### How it works

1. A business registers and creates a **workspace** (company name, address, phone)
2. Sets up an **AI voice assistant** bound to a real phone number
3. Configures a **calendar** — business hours, available time slots
4. When someone **calls the number**, the CallerAI engine handles the call:
   - Greets the caller on behalf of the business
   - Answers questions (address, hours, etc.)
   - Books appointments into the calendar
   - Handles the conversation politely and professionally

### Related projects

| Project | Repo | Role |
|---------|------|------|
| **CallerAI** | `fszontagh/callerai` | The telephony AI engine — SIP gateway, audio pipeline, LLM, automation, assistant management. Handles actual call processing. |
| **Smartbotic Microbit** (this) | `fszontagh/smartbotic-microbit` | Admin UI on top of CallerAI — workspaces, users, calendar, appointment booking. Calls the CallerAI API via `CallerAIClient`. |
| **Smartbotic** | `fszontagh/smartbotic` | Flow/automation platform (node-based, QuickJS). Independent project. |
| **Smartbotic CRM** | `fszontagh/smartbotic-crm` | CRM system — customer management, documents, LLM tools. Independent project. |

## Features

- **Multi-Workspace Management**: Support for multiple workspaces with team collaboration
- **User Authentication & Authorization**: JWT-based authentication with role-based access control (Owner, Admin, Member, Guest)
- **Calendar & Appointment System**: Manage calendars, time slots, and appointments with availability tracking
- **AI Voice Assistants**: Integration with CallerAI for creating and managing AI-powered voice assistants
- **Team Collaboration**: Invite members, manage roles, and collaborate across workspaces
- **Email Notifications**: SMTP integration for invitation emails and notifications
- **RESTful API**: Comprehensive REST API for all platform features
- **Web UI**: React-based modern web interface built with TypeScript and Tailwind CSS

## Architecture

Smartbotic Microbit consists of three main components:

1. **Backend Service** (`smartbotic-microbit`): C++20-based HTTP service with RESTful API
2. **Database Service** (`smartbotic-database`): Custom database service for persistent storage
3. **Web UI**: React + TypeScript frontend application

For detailed architecture information, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## Quick Start

### Prerequisites

- Linux (Debian/Ubuntu recommended)
- CMake 3.20+
- C++20 compatible compiler (GCC 11+ or Clang 14+)
- Node.js 18+ and npm (for WebUI development)
- Git

### Installation

The easiest way to install Smartbotic Microbit is using the pre-built packages:

```bash
# Download the latest release packages
# Install using the provided installer
sudo ./packaging/scripts/install.sh smartbotic-*.tar.gz

# Configure the service
sudo cp /etc/smartbotic/smartbotic.env.default /etc/smartbotic/smartbotic.env
sudo nano /etc/smartbotic/smartbotic.env  # Set JWT_SECRET, SMTP, and CallerAI settings

# Start the services
sudo systemctl enable smartbotic-database smartbotic-microbit
sudo systemctl start smartbotic-database
sudo systemctl start smartbotic-microbit
```

For detailed installation and deployment instructions, see [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).

### Development Setup

For development and building from source:

```bash
# Clone the repository with submodules
git clone --recursive https://github.com/fszontagh/smartbotic-microbit.git
cd smartbotic-microbit

# Build the backend
mkdir build && cd build
cmake ..
make -j$(nproc)

# Build the WebUI
cd ../webui
npm install
npm run build
```

For complete development setup instructions, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## Configuration

The main configuration file is located at `/etc/smartbotic/microbit.json` (or `config/microbit.json` for development).

Key configuration sections:

- **Database**: Connection settings for the database service
- **HTTP**: Server bind address, port, and static file serving
- **Auth**: JWT settings and password policy
- **SMTP**: Email server configuration for notifications
- **CallerAI**: API credentials for AI assistant integration
- **CORS**: Cross-origin resource sharing settings
- **Rate Limiting**: API rate limiting configuration

Environment variables can be used to override configuration values using the `${VAR_NAME:default}` syntax.

## API Documentation

The platform provides a comprehensive RESTful API. Key endpoint groups:

- `/api/v1/auth/*` - Authentication (register, login, refresh tokens)
- `/api/v1/users/*` - User management
- `/api/v1/workspaces/*` - Workspace CRUD and member management
- `/api/v1/workspaces/:id/assistants/*` - AI assistant management
- `/api/v1/workspaces/:id/calendars/*` - Calendar and appointment management
- `/api/v1/invitations/*` - Workspace invitations
- `/api/v1/settings/*` - Global and workspace settings

For complete API documentation, see [docs/API.md](docs/API.md).

## Usage

### Creating a Workspace

After registering and logging in, create your first workspace:

```bash
curl -X POST http://localhost:8090/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Company",
    "company_name": "Acme Corp",
    "address": "123 Main St",
    "phone": "+1-555-0100"
  }'
```

### Inviting Team Members

```bash
curl -X POST http://localhost:8090/api/v1/workspaces/WORKSPACE_ID/invitations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@example.com",
    "role": "member"
  }'
```

### Creating an AI Assistant

```bash
curl -X POST http://localhost:8090/api/v1/workspaces/WORKSPACE_ID/assistants \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "phone_number": "+1-555-0200",
    "instructions": "You are a helpful customer support assistant..."
  }'
```

## Documentation

- [Architecture Overview](docs/ARCHITECTURE.md) - System design and component interaction
- [Development Guide](docs/DEVELOPMENT.md) - Building and developing the project
- [API Reference](docs/API.md) - Complete API endpoint documentation
- [Deployment Guide](docs/DEPLOYMENT.md) - Installation and deployment instructions

## Technology Stack

**Backend:**
- C++20
- httplib (HTTP server)
- nlohmann/json (JSON parsing)
- spdlog (Logging)
- JWT-CPP (JWT tokens)
- BCrypt (Password hashing)
- gRPC (Database communication)

**Frontend:**
- React 19
- TypeScript
- Tailwind CSS 4
- React Router
- TanStack Query
- Zustand (State management)
- Vite (Build tool)

**Database:**
- Custom smartbotic-database service
- Protocol Buffers (gRPC interface)

## License

Copyright © 2024 Smartbotics AI

## Support

For issues and questions, please use the GitHub issue tracker or contact support@smartbotics.ai.