通用机器人

🏗️ Component Dependency Graph

┌─────────────────────────────────────────────────────────────────┐
│                         Client Layer                            │
├─────────────────────────────────────────────────────────────────┤
│  botui (Web UI)    │  botapp (Desktop)   │  botplugin (Ext)   │
│  HTMX + Axum       │  Tauri 2 Wrapper    │  Browser Extension  │
└─────────┬───────────────────┬──────────────────┬─────────────────┘
          │                   │                  │
          └───────────────────┼──────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   botlib          │
                    │  (Shared Types)   │
                    └─────────┬─────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
    ┌─────▼─────┐      ┌─────▼─────┐      ┌─────▼─────┐
    │ botserver │      │ bottest   │      │ botdevice  │
    │ API Core  │      │ Tests     │      │ IoT/Device │
    └───────────┘      └───────────┘      └───────────┘

Dependency Rules

Key Principle: botlib contains ONLY shared types and utilities. No business logic. All business logic lives in botserver or specialized crates.

Check for duplicate dependencies

cargo tree --duplicates

Remove unused dependencies

cargo machete

📦 Component Installation System

Components are defined in botserver/3rdparty.toml and managed by the PackageManager (botserver/src/core/package_manager/):

[components.cache]
name = "Valkey Cache (Redis-compatible)"
url = "https://github.com/valkey-io/valkey/archive/refs/tags/8.0.2.tar.gz"
filename = "valkey-8.0.2.tar.gz"

[components.llm]
name = "Llama.cpp Server"
url = "https://github.com/ggml-org/llama.cpp/releases/download/b7345/llama-b7345-bin-ubuntu-x64.zip"
filename = "llama-b7345-bin-ubuntu-x64.zip"

Installation Flow: 1. Download: Components downloaded to botserver-installers/ (cached) 2. Extract/Build: Binaries placed in botserver-stack/bin/<component>/ 3. Configure: Config files generated in botserver-stack/conf/<component>/ 4. Start: Components started with proper TLS certificates 5. Monitor: Components monitored and auto-restarted if needed

Bootstrap Process: - First run: Full bootstrap (downloads, installs, configures all components) - Subsequent runs: Only starts existing components (uses cached binaries) - Config stored in: botserver-stack/conf/system/bootstrap.json

Build release binary first

cargo build --release -p botserver

UI File Deployment - Production Options

Option 1: Embedded UI (Recommended for Production)

The embed-ui feature compiles UI files directly into the botui binary, eliminating the need for separate file deployment:

```bash

Build with embedded UI files

cargo build --release -p botui --features embed-ui

The binary now contains all UI files - no additional deployment needed!

This is automatically available in development builds

**Option 3: Manual File Deployment (Legacy)**

If you need to deploy UI files separately (not recommended):

Deploy UI files to production location

./botserver/deploy/deploy-ui.sh /opt/gbo

Verify deployment

ls -la /opt/gbo/bin/ui/suite/index.html ```

See botserver/deploy/README.md for deployment scripts.

Build Commands

```bash

Build workspace

cargo build

Quick Start

🤖 AI Agent Guidelines

For LLM instructions, coding rules, security directives, testing workflows, and error handling patterns, see AGENTS.md.

---

📋 Project-Specific Guidelines

Each crate has its own README.md with specific guidelines:

🏗️ BotServer Component Architecture

🔧 Infrastructure Components (Auto-Managed)

BotServer automatically installs, configures, and manages all infrastructure components on first run. DO NOT manually start these services - BotServer handles everything.

Automatic Service Lifecycle: 1. Start: When botserver starts, it automatically launches all infrastructure components (PostgreSQL, Vault, MinIO, Valkey, Qdrant, etc.) 2. Credentials: BotServer retrieves all service credentials (passwords, tokens, API keys) from Vault 3. Connection: BotServer uses these credentials to establish secure connections to each service 4. Query: All database queries, cache operations, and storage requests are authenticated using Vault-managed credentials

Credential Flow:

botserver starts
    ↓
Launch PostgreSQL, MinIO, Valkey, Qdrant
    ↓
Connect to Vault
    ↓
Retrieve service credentials (from database)
    ↓
Authenticate with each service using retrieved credentials
    ↓
Ready to handle requests

🔒 Component Communication

All components communicate through internal networks with mTLS: - Vault: mTLS for secrets access - PostgreSQL: TLS encrypted connections - MinIO: TLS with client certificates - Zitadel: mTLS for user authentication

Certificates auto-generated in: botserver-stack/conf/system/certificates/

📊 Component Status

Check component status anytime: ```bash

Check if all components are running

ps aux | grep -E "vault|postgres|minio|zitadel|qdrant|valkey" | grep -v grep

View component logs

tail -f botserver-stack/logs/vault/vault.log tail -f botserver-stack/logs/tables/postgres.log tail -f botserver-stack/logs/drive/minio.log

Test component connectivity

cd botserver-stack/bin/vault && ./vault status cd botserver-stack/bin/cache && ./valkey-cli ping ```

---

📦 Module Responsibility Matrix

botserver/src/ Module Structure

⚠️ CRITICAL: Submodule Push Workflow

When making changes to any submodule (botserver, botui, botlib, etc.):

1. Commit and push changes within the submodule directory:

   cd botserver
   git add .
   git commit -m "Your changes"
   git push pragmatismo main
   git push github main
   

2. Update the global gb repository submodule reference:

   cd ..  # Back to gb root
   git add botserver
   git commit -m "Update botserver submodule to latest commit"
   git push pragmatismo main
   git push github main
   

Failure to push the global gb repository will cause submodule changes to not trigger CI/CD pipelines.

Both repositories must be pushed for changes to take effect in production.

---

Development Workflow

1. Read this README.md (workspace structure)
2. Read AGENTS.md (coding rules & workflows)
3. BEFORE creating any .md file, search botbook/ for existing documentation
4. Read <project>/README.md (project-specific rules)
5. Use diagnostics tool to check warnings
6. Fix all warnings with full file rewrites
7. Verify with diagnostics after each file
8. Never suppress warnings with #[allow()]

---