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

🤝 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.

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

Name		Name	Last commit message	Last commit date
Latest commit History 387 Commits
.forgejo/workflows		.forgejo/workflows
src		src
.gitignore		.gitignore
LICENSE		LICENSE
PROMPT.md		PROMPT.md
README.md		README.md
book.toml		book.toml

License

GeneralBots/botbook

Folders and files

Latest commit

History

Repository files navigation

General Bots Documentation (BotBook)

Overview

🏗️ Architecture

📦 General Bots Repositories

🚀 Quick Start

Prerequisites

Run the Server

Run the Desktop App

Build Documentation

✨ Key Features

🤖 Multi-Vendor LLM API

🔧 MCP + LLM Tools Generation

💾 Semantic Caching

🌐 Web Automation Engine

📊 Enterprise Data Connectors

🔄 Git-like Version Control

🎯 4 Essential Keywords

📁 Documentation Structure

📚 Documentation Writing Guidelines

✅ Keyword Naming Rules - MANDATORY

Correct Syntax Examples

❌ NEVER Use Underscores

🎨 Official Icons - MANDATORY

Usage in Documentation

Required Icons

🚫 NO ASCII Diagramrams - MANDATORY

❌ Prohibited ASCII Patterns

✅ What to Use Instead

🎨 SVG Diagram Guidelines

💬 Conversation Examples

📋 Source Code References

📖 Documentation Accuracy Rules

🏛️ Architecture Details

botserver (Core)

botui (Web Interface)

botapp (Desktop)

botlib (Shared Library)

🛡️ Security

🆚 Why General Bots?

🔗 Links

🤝 Contributing

Contributors

🔑 Remember

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 7

Uh oh!

Languages

Packages