smartbotic-microbit/docs/ARCHITECTURE.md

Smartbotic Microbit Architecture

This document describes the architecture and design of the Smartbotic Microbit platform.

System Overview

Smartbotic Microbit is a multi-tier application consisting of three primary components:

┌─────────────────┐
│   Web Browser   │  (React/TypeScript SPA)
└────────┬────────┘
         │ HTTP/REST
         ▼
┌─────────────────┐
│ Microbit Service│  (C++ HTTP Server)
└────────┬────────┘
         │ gRPC
         ▼
┌─────────────────┐
│ Database Service│  (Custom Storage Engine)
└─────────────────┘

Component Architecture

1. Microbit Service (Backend)

The main application server implemented in C++20, providing RESTful API endpoints and business logic.

Core Components

App (src/app.cpp)

• Main application entry point
• Manages component lifecycle
• Initializes all services, stores, and routes
• HTTP server configuration

HTTP Layer

• Uses cpp-httplib for HTTP server
• RESTful API endpoints organized by feature
• JWT-based authentication middleware
• CORS support
• Request/response handling

Module Structure

src/
├── main.cpp              # Application entry point
├── app.{hpp,cpp}         # Main app class
├── routes/               # HTTP route handlers
│   ├── auth_routes       # Authentication endpoints
│   ├── user_routes       # User management
│   ├── workspace_routes  # Workspace CRUD
│   ├── assistant_routes  # AI assistant management
│   ├── calendar_routes   # Calendar & appointments
│   ├── invitation_routes # Team invitations
│   └── settings_routes   # Settings management
├── services/             # Business logic layer
│   ├── auth_service      # Authentication logic
│   ├── workspace_service # Workspace operations
│   ├── invitation_service# Invitation workflow
│   ├── assistant_service # Assistant management
│   └── calendar_service  # Calendar operations
└── stores/               # Data access layer
    ├── user_store        # User data operations
    ├── workspace_store   # Workspace data
    ├── assistant_store   # Assistant data
    ├── calendar_store    # Calendar data
    ├── invitation_store  # Invitation data
    └── settings_store    # Settings data

Library Modules

lib/
├── auth/                 # Authentication & authorization
│   ├── jwt_utils         # JWT token generation/validation
│   ├── bcrypt_utils      # Password hashing
│   └── auth_middleware   # Request authentication
├── common/               # Common utilities
│   ├── config_loader     # Configuration parsing
│   ├── logging           # Logging utilities
│   └── utils             # General utilities
├── smtp/                 # Email sending
│   └── smtp_client       # SMTP client implementation
└── callerai/             # CallerAI integration
    └── callerai_client   # CallerAI API client

2. Database Service

Custom database service providing persistent storage via gRPC interface.

Location: external/smartbotic-database (git submodule)

Key Features:

• Collection-based storage model
• Document-oriented (JSON documents)
• Query and indexing support
• Migration system
• gRPC API

Client Interface: smartbotic::database::Client

• CRUD operations on collections
• Query execution
• Transaction support

3. Web UI

Modern single-page application built with React and TypeScript.

webui/
├── src/
│   ├── main.tsx          # Application entry point
│   ├── App.tsx           # Root component & routing
│   ├── api/              # Backend API client
│   ├── pages/            # Page components
│   │   ├── auth/         # Login, Register
│   │   ├── dashboard/    # Main dashboard
│   │   ├── members/      # Team member management
│   │   ├── invitations/  # Invitation management
│   │   ├── assistants/   # AI assistant pages
│   │   └── calendar/     # Calendar & appointments
│   ├── components/       # Reusable UI components
│   └── stores/           # Client-side state (Zustand)
├── package.json
└── vite.config.ts

Key Technologies:

• React 19: UI framework
• TypeScript: Type safety
• Tailwind CSS: Styling
• React Router: Client-side routing
• TanStack Query: Server state management
• Zustand: Client state management
• Vite: Build tool and dev server

Data Model

Core Entities

User

• id: Unique identifier (usr_xxx)
• email: User email (unique)
• password_hash: BCrypt hashed password
• display_name: User's display name
• status: Account status (active, suspended)

Workspace

• id: Unique identifier (ws_xxx)
• name: Workspace name
• company_name: Company name
• address: Physical address
• phone: Contact phone number

WorkspaceMember

• id: Unique identifier (wm_xxx)
• workspace_id: Reference to workspace
• user_id: Reference to user
• role: Member role (owner, admin, member, guest)

Assistant (AI Voice Assistant)

• id: Unique identifier (ast_xxx)
• workspace_id: Owning workspace
• name: Assistant name
• phone_number: Phone number for calls
• instructions: AI behavior instructions
• callerai_id: CallerAI platform ID
• status: Active/inactive status

Calendar

• id: Unique identifier (cal_xxx)
• workspace_id: Owning workspace
• name: Calendar name
• assistant_id: Associated assistant (optional)

TimeSlot

• id: Unique identifier (ts_xxx)
• calendar_id: Parent calendar
• day_of_week: Day (0=Sunday, 6=Saturday)
• start_time: Slot start time (HH:MM)
• end_time: Slot end time (HH:MM)

Appointment

• id: Unique identifier (apt_xxx)
• calendar_id: Associated calendar
• start_time: Appointment start (ISO 8601)
• end_time: Appointment end (ISO 8601)
• customer_name, customer_phone, customer_email: Customer info
• notes: Appointment notes
• status: pending, confirmed, cancelled

Invitation

• id: Unique identifier (inv_xxx)
• workspace_id: Target workspace
• email: Invitee email
• role: Intended role
• token: Unique invitation token
• status: pending, accepted, rejected

Session

• id: Unique identifier (ses_xxx)
• user_id: Associated user
• Used for refresh token validation

Authentication & Authorization

Authentication Flow

1. Registration: POST /api/v1/auth/register

   • Validate password policy
   • Hash password with BCrypt
   • Create user record
   • Create session
   • Return JWT tokens (access + refresh)

2. Login: POST /api/v1/auth/login

   • Validate credentials
   • Delete old sessions
   • Create new session
   • Return JWT tokens

3. Token Refresh: POST /api/v1/auth/refresh

   • Validate refresh token
   • Check session validity
   • Issue new access token

Authorization Model

JWT Claims:

• sub: User ID
• email: User email
• role: Global role (currently "user")
• exp: Expiration timestamp

Workspace Roles (per workspace):

• Owner: Full control, can delete workspace
• Admin: Manage members, assistants, calendars
• Member: View and use workspace resources
• Guest: Read-only access

Role Hierarchy:

Owner > Admin > Member > Guest

Middleware Flow

Request → Auth Middleware → Route Handler
           │
           ├─ Extract JWT from Authorization header
           ├─ Validate token signature
           ├─ Check expiration
           ├─ Store AuthContext (user_id, email, role)
           └─ Continue or reject (401)

Route handlers check workspace membership and roles as needed.

Configuration System

Configuration File Structure

JSON-based configuration with environment variable substitution:

{
  "database": {
    "rpc_address": "${DB_ADDRESS:localhost:9004}"
  },
  "auth": {
    "jwt_secret": "${JWT_SECRET:change-me-in-production}"
  }
}

Syntax: ${VAR_NAME:default_value}

Configuration Loading

ConfigLoader class:

• Loads JSON configuration file
• Resolves environment variables at runtime
• Provides type-safe getters with defaults

Configuration Files

• Development: config/microbit.json
• Production: /etc/smartbotic/microbit.json
• Environment: /etc/smartbotic/smartbotic.env (sourced by systemd)

External Integrations

CallerAI Integration

Purpose: Create and manage AI-powered voice assistants

Client: callerai::CallerAIClient

Operations:

• Create assistant with phone number
• Update assistant configuration
• Delete assistant
• List assistants

Configuration:

• callerai.api_url: CallerAI API endpoint
• callerai.api_key: API authentication key
• callerai.timeout_sec: Request timeout

SMTP Integration

Purpose: Send email notifications (invitations, etc.)

Client: smtp::SmtpClient

Operations:

• Send invitation emails
• Configurable templates

Configuration:

• smtp.host: SMTP server hostname
• smtp.port: SMTP server port (default 587)
• smtp.username: SMTP authentication username
• smtp.password: SMTP authentication password
• smtp.from_address: Sender email address
• smtp.use_tls: Enable TLS (recommended)

HTTP Server Architecture

Request Flow

HTTP Request
    │
    ├─ CORS Middleware (if enabled)
    │    └─ Add CORS headers
    │
    ├─ Rate Limiting (if enabled)
    │    └─ Check request count
    │
    ├─ Auth Middleware (protected routes)
    │    └─ Validate JWT token
    │
    └─ Route Handler
         ├─ Parse request body
         ├─ Validate input
         ├─ Check authorization (workspace roles)
         ├─ Call service layer
         ├─ Access data via stores
         └─ Return JSON response

Error Handling

Standard error responses:

{
  "error": "Error message"
}

HTTP Status Codes:

• 200 OK - Success
• 201 Created - Resource created
• 400 Bad Request - Invalid input
• 401 Unauthorized - Missing/invalid token
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Static File Serving

The HTTP server can serve the WebUI static files:

{
  "http": {
    "static_files": {
      "enabled": true,
      "path": "webui/dist"
    }
  }
}

When enabled, all non-API routes serve static files from the configured path.

Build System

CMake Structure

CMakeLists.txt              # Root build configuration
├── cmake/
│   ├── CompilerFlags.cmake # Compiler settings
│   ├── FindPackages.cmake  # External package detection
│   └── Dependencies.cmake  # Dependency management
├── lib/CMakeLists.txt      # Library builds
│   ├── auth/
│   ├── common/
│   ├── smtp/
│   └── callerai/
└── src/CMakeLists.txt      # Main application build

Build Options

• CMAKE_BUILD_TYPE: Release|Debug (default: Release)
• BUILD_TESTS: Build tests (default: OFF)
• BUNDLE_DATABASE: Include database service in build (default: OFF)

Dependencies

System Libraries:

• OpenSSL (libssl-dev)
• gRPC and Protobuf
• Abseil (from gRPC/Protobuf)

Bundled Libraries (via CMake FetchContent):

• cpp-httplib
• nlohmann/json
• spdlog
• jwt-cpp
• bcrypt (custom implementation)

Deployment Architecture

Systemd Services

Two systemd services run the platform:

1. smartbotic-database.service

   • Runs the database service
   • Port: 9004 (gRPC)
   • Data: /var/lib/smartbotic/database/

2. smartbotic-microbit.service

   • Runs the main application
   • Port: 8090 (HTTP)
   • Depends on database service

File System Layout

/opt/smartbotic/
├── bin/
│   ├── smartbotic-database
│   └── smartbotic-microbit
└── share/smartbotic/
    └── nginx/
        └── smartbotic.conf.template

/etc/smartbotic/
├── database.json
├── microbit.json
└── smartbotic.env

/var/lib/smartbotic/
├── database/
│   ├── storage/
│   └── migrations/
└── microbit/
    └── webui/

/var/log/smartbotic/
├── database.log
└── microbit.log

Nginx Reverse Proxy (Optional)

Browser → Nginx (443) → Microbit Service (8090)

Nginx provides:

• TLS termination
• Reverse proxy to backend
• Static file serving (WebUI)
• Request logging

Configuration template: packaging/nginx/smartbotic.conf.template

Security Considerations

Password Security

• BCrypt hashing with salt
• Configurable password policy (minimum length, character requirements)
• Passwords never logged or returned in responses

Token Security

• JWT with HMAC-SHA256 signature
• Short-lived access tokens (default: 15 minutes)
• Long-lived refresh tokens (default: 7 days)
• Refresh tokens tied to sessions (revocable)

API Security

• All protected endpoints require valid JWT
• Workspace operations check membership
• Role-based authorization enforced
• Rate limiting available

Configuration Security

• Sensitive values via environment variables
• Config files readable only by service user
• Database connections over localhost or private network

Logging

Logging Framework: spdlog

Log Levels:

• trace: Detailed debug information
• debug: Debug information
• info: General information (default)
• warn: Warning messages
• error: Error conditions
• critical: Critical errors

Configuration: log_level in config file

Output:

• Development: Console output
• Production: File output (/var/log/smartbotic/microbit.log)

Performance Considerations

Database Access

• Connection pooling (managed by database client)
• Efficient queries with indexes
• Minimal round-trips per request

HTTP Server

• Single-threaded event loop (cpp-httplib)
• Non-blocking I/O where possible
• Keep-alive connections supported

Caching

• JWT validation caching (implicit in middleware)
• No application-level caching currently implemented

Rate Limiting

• In-memory rate limiting per IP
• Configurable limits: rate_limit.requests_per_minute

Future Considerations

Scalability

• Horizontal scaling requires session store (Redis)
• Database service already supports clustering
• Load balancing via Nginx

Monitoring

• Prometheus metrics endpoint (planned)
• Health check endpoints
• Performance metrics

Testing

• Unit tests (planned: BUILD_TESTS)
• Integration tests
• API endpoint tests

Conclusion

The Smartbotic Microbit platform follows a layered architecture with clear separation of concerns:

• Routes: HTTP request handling
• Services: Business logic
• Stores: Data access

This design promotes maintainability, testability, and extensibility while providing a robust foundation for workspace management and AI assistant deployment.