General Bots Documentation (BotBook)

Version: 6.2.0
Purpose: Comprehensive documentation for General Bots (mdBook format)

---

Overview

BotBook is the official documentation repository for General Bots, built using mdBook. It provides comprehensive guides, API references, tutorials, and architectural documentation for the entire General Bots platform - an enterprise-grade LLM orchestrator and AI automation platform.

For the latest live documentation, visit docs.pragmatismo.com.br.

---

🏗️ Architecture

---

📦 General Bots Repositories

Repository	Description	Status
botserver	Core API server - LLM orchestration, automation, integrations	✅ Production
botui	Pure web UI - HTMX-based interface (suite & minimal)	✅ Production
botapp	Tauri desktop wrapper - native file access, system tray	✅ Production
botlib	Shared Rust library - common types, HTTP client, utilities	✅ Production
bottemplates	Templates - bots, apps, prompts, UI components	✅ Production
botbook	Documentation - mdBook format, multi-language	✅ Production

---

🚀 Quick Start

Prerequisites

• Rust (latest stable) - Install from rustup.rs
• Git - Download from git-scm.com
• mdBook - cargo install mdbook

Run the Server

# Clone and run
git clone https://github.com/GeneralBots/botserver
cd botserver
cargo run

On first run, botserver automatically:

• Installs required components (PostgreSQL, S3 storage, Cache, LLM)
• Sets up database with migrations
• Downloads AI models
• Starts HTTP server at http://127.0.0.1:8080

Run the Desktop App

# Clone botui (pure web)
git clone https://github.com/GeneralBots/botui
cd botui
cargo run  # Starts web server at :3000

# In another terminal, clone and run botapp (Tauri desktop)
git clone https://github.com/GeneralBots/botapp
cd botapp
cargo tauri dev

Build Documentation

# Clone botbook
git clone https://github.com/GeneralBots/botbook
cd botbook

# Build documentation
mdbook build

# Serve locally with hot reload
mdbook serve --open

---

✨ Key Features

🤖 Multi-Vendor LLM API

Unified interface for OpenAI, Groq, Claude, Anthropic, and local models.

🔧 MCP + LLM Tools Generation

Instant tool creation from code and functions - no complex configurations.

💾 Semantic Caching

Intelligent response caching achieving 70% cost reduction on LLM calls.

🌐 Web Automation Engine

Browser automation combined with AI intelligence for complex workflows.

📊 Enterprise Data Connectors

Native integrations with CRM, ERP, databases, and external services.

🔄 Git-like Version Control

Full history with rollback capabilities for all configurations and data.

---

🎯 4 Essential Keywords

General Bots provides a minimal, focused system:

USE KB "knowledge-base"    ' Load knowledge base into vector database
CLEAR KB "knowledge-base"  ' Remove KB from session
USE TOOL "tool-name"       ' Make tool available to LLM
CLEAR TOOLS                ' Remove all tools from session

---

📁 Documentation Structure

botbook/
├── book.toml          # mdBook configuration
├── src/
│   ├── SUMMARY.md     # Table of contents
│   ├── README.md      # Introduction
│   ├── 01-introduction/   # Quick Start
│   ├── 02-templates/      # Package System
│   ├── 03-knowledge-base/ # Knowledge Base
│   ├── 04-gbui/          # UI Interface
│   ├── 06-gbdialog/       # BASIC Dialogs
│   ├── 08-config/         # Configuration
│   ├── 10-rest/           # REST API
│   ├── 12-auth/           # Authentication
│   └── assets/            # Images, diagrams
├── i18n/              # Translations
└── book/              # Generated output

---

📚 Documentation Writing Guidelines

✅ Keyword Naming Rules - MANDATORY

Keywords NEVER use underscores. Always use spaces.

Write This	NOT This
SEND MAIL	SEND_MAIL
GENERATE PDF	GENERATE_PDF
MERGE PDF	MERGE_PDF
DELETE	DELETE_HTTP
SET HEADER	SET_HEADER
FOR EACH	FOR_EACH

Correct Syntax Examples

SEND MAIL to, subject, body, attachments
GENERATE PDF template, data, output
MERGE PDF files, output
DELETE "url"
ON ERROR RESUME NEXT
SET BOT MEMORY key, value
KB STATISTICS

❌ NEVER Use Underscores

SEND_MAIL          ' WRONG!
GENERATE_PDF       ' WRONG!
DELETE_HTTP        ' WRONG!

---

🎨 Official Icons - MANDATORY

NEVER generate icons with LLM. Use official SVG icons from botui/ui/suite/assets/icons/

Usage in Documentation

<!-- Reference icons in docs -->
![Chat](../assets/icons/gb-chat.svg)

<!-- With HTML for sizing -->
<img src="../assets/icons/gb-analytics.svg" alt="Analytics" width="24">

Required Icons

ui/suite/assets/icons/
├── gb-logo.svg        # Main GB logo
├── gb-bot.svg         # Bot/assistant
├── gb-analytics.svg   # Analytics
├── gb-calendar.svg    # Calendar
├── gb-chat.svg        # Chat
├── gb-drive.svg       # File storage
├── gb-mail.svg        # Email
├── gb-meet.svg        # Video meetings
├── gb-tasks.svg       # Task management
└── ...

All icons use stroke="currentColor" for CSS theming.

---

🚫 NO ASCII Diagramrams - MANDATORY

NEVER use ASCII art diagrams. ALL diagrams must be SVG.

❌ Prohibited ASCII Patterns

┌─────────┐    ╔═══════╗    +-------+
│  Box    │    ║ Box   ║    | Box   |
└─────────┘    ╚═══════╝    +-------+

✅ What to Use Instead

Instead of...	Use...
ASCII box diagrams	SVG diagrams in assets/
ASCII flow charts	SVG with arrows and boxes
ASCII directory trees	Markdown tables

---

🎨 SVG Diagram Guidelines

All SVGs must support light/dark modes:

<style>
  .title-text { fill: #1E1B4B; }
  .main-text { fill: #334155; }
  
  @media (prefers-color-scheme: dark) {
    .title-text { fill: #F1F5F9; }
    .main-text { fill: #E2E8F0; }
  }
</style>

---

💬 Conversation Examples

Use WhatsApp-style HTML format for bot interactions:

<div class="wa-chat">
  <div class="wa-message bot">
    <div class="wa-bubble">
      <p>Hello! How can I help?</p>
      <div class="wa-time">10:30</div>
    </div>
  </div>
  <div class="wa-message user">
    <div class="wa-bubble">
      <p>I want to enroll</p>
      <div class="wa-time">10:31</div>
    </div>
  </div>
</div>

---

📋 Source Code References

Topic	Source Location
BASIC Keywords	botserver/src/basic/keywords/
Database Models	botserver/src/shared/models.rs
API Routes	botserver/src/core/urls.rs
Configuration	botserver/src/core/config/
Templates	botserver/templates/

---

📖 Documentation Accuracy Rules

- All documentation MUST match actual source code
- Extract real keywords from botserver/src/basic/keywords/
- Use actual examples from botserver/templates/
- Version numbers must be 6.2.0
- No placeholder content - only verified features

---

🏛️ Architecture Details

botserver (Core)

The main API server handling:

• LLM orchestration and prompt management
• Multi-channel communication (WhatsApp, Teams, Email, Web)
• File storage and drive management
• Task scheduling and automation
• Authentication and authorization

botui (Web Interface)

Pure web UI with zero native dependencies:

• Suite: Full-featured multi-app interface
• Minimal: Lightweight single-page chat
• HTMX-powered for minimal JavaScript
• Works in any browser

botapp (Desktop)

Tauri wrapper adding native capabilities:

• Local file system access
• System tray integration
• Native dialogs and notifications
• Desktop-specific features

botlib (Shared Library)

Common Rust code shared across projects:

• HTTP client for botserver communication
• Shared types and models
• Branding and configuration utilities
• Error handling

---

🛡️ Security

• AGPL-3.0 License - True open source with contribution requirements
• Self-hosted - Your data stays on your infrastructure
• Enterprise-grade - 5+ years of stability
• No vendor lock-in - Open protocols and standards

Report security issues to: security@pragmatismo.com.br

---

🆚 Why General Bots?

vs. Alternative	General Bots Advantage
ChatGPT/Claude	Automates entire business processes, not just chat
n8n/Make	Simpler approach with minimal programming
Microsoft 365	User control, not locked ecosystems
Salesforce	Open-source AI orchestration connecting all systems

---

🔗 Links

• Website: pragmatismo.com.br
• Documentation: docs.pragmatismo.com.br
• BotBook: Complete Documentation
• Quick Start: Get Started in Minutes
• API Reference: REST API Documentation
• Architecture: System Architecture Guide
• Stack Overflow: Tag questions with generalbots
• Video Tutorial: 7 AI General Bots LLM Templates

---

🤝 Contributing

We welcome contributions! See our Contributing Guidelines.

Contributors

---

🔑 Remember

• Accuracy - Must match botserver source code
• Completeness - No placeholder sections
• Clarity - Accessible to BASIC enthusiasts
• Keywords - NEVER use underscores - always spaces
• NO ASCII art - Use SVG diagrams only
• Official icons - Use icons from botui/ui/suite/assets/icons/
• Version 6.2.0 - Always reference 6.2.0
• GIT WORKFLOW - ALWAYS push to ALL repositories (github, pragmatismo)

---

📄 License

General Bots is licensed under AGPL-3.0.

According to our dual licensing model, this program can be used either under the terms of the GNU Affero General Public License, version 3, or under a proprietary license.

Copyright (c) pragmatismo.com.br. All rights reserved.

---

Code Name: Guaribas (a city in Brazil, state of Piauí)

"No one should have to do work that can be done by a machine." - Roberto Mangabeira Unger