botserver/docs/src/chapter-02/gbai.md

# .gbai Architecture

**A bot is just a folder.** The `.gbai` extension marks a directory as a BotServer package containing everything needed to run a conversational AI bot - scripts, documents, configuration, and themes.

## The Dead Simple Structure

```
my-bot.gbai/                    # This folder = your entire bot
  my-bot.gbdialog/           # BASIC conversation scripts
  my-bot.gbkb/               # Documents for Q&A
  my-bot.gbot/               # Configuration
  my-bot.gbtheme/            # Optional UI customization
```

That's it. No manifests, no build files, no dependencies. Copy the folder to deploy.

### Visual Architecture
### Architecture

![Package Structure](./assets/package-structure.svg)

## How Bootstrap Finds Bots

At startup, BotServer scans `templates/` for any folder ending in `.gbai`:

```
templates/
  default.gbai/       → Creates bot at /default
  support.gbai/       → Creates bot at /support  
  sales.gbai/         → Creates bot at /sales
```

Each `.gbai` becomes a URL endpoint automatically. Zero configuration.

## What Goes Where

### .gbdialog/ - Your Bot's Brain

BASIC scripts that control conversation flow:

```
my-bot.gbdialog/
  start.bas           # Runs when session starts
  auth.bas            # Login flow
  tools/              # Callable functions
    book-meeting.bas
    check-status.bas
  handlers/           # Event responses
    on-email.bas
```

Example `start.bas`:
```basic
TALK "Hi! I'm your assistant."
answer = HEAR
TALK "I can help you with: " + answer
```

### .gbkb/ - Your Bot's Knowledge

Documents organized by topic:

```
my-bot.gbkb/
  policies/           # HR documents
    vacation.pdf
    handbook.docx
  products/           # Product info
    catalog.pdf
    pricing.xlsx
  support/            # Help docs
    faq.md
```

Each folder becomes a searchable collection. Drop files in, bot learns automatically.

### .gbot/ - Your Bot's Settings

Single `config.csv` file with key-value pairs:

```csv
llm-model,gpt-3.5-turbo
temperature,0.7
max-tokens,2000
welcome-message,Hello! How can I help?
session-timeout,1800
```

No complex JSON or YAML. Just simple CSV that opens in Excel.

### .gbtheme/ - Your Bot's Look (Optional)

Custom web interface styling:

```
my-bot.gbtheme/
  styles.css          # Custom CSS
  logo.png           # Brand assets
  templates/         # HTML overrides
    chat.html
```

If missing, uses default theme. Most bots don't need this.

## Real Example: Support Bot

Here's a complete customer support bot:

```
support.gbai/
  support.gbdialog/
    start.bas
    tools/
      create-ticket.bas
      check-status.bas
  support.gbkb/
    faqs/
      common-questions.pdf
    guides/
      troubleshooting.docx
  support.gbot/
    config.csv
```

`start.bas`:
```basic
USE KB "faqs"
USE KB "guides"
USE TOOL "create-ticket"
USE TOOL "check-status"

TALK "Support bot ready. How can I help?"
```

`create-ticket.bas`:
```basic
PARAM issue, priority
DESCRIPTION "Creates support ticket"

ticket_id = GENERATE_ID()
SAVE "tickets.csv", ticket_id, issue, priority, NOW()
TALK "Ticket #" + ticket_id + " created"
```

`config.csv`:
```csv
llm-model,gpt-3.5-turbo
bot-name,TechSupport
greeting,Welcome to support!
```

## Deployment = Copy Folder

### Local Development
```bash
cp -r my-bot.gbai/ templates/
./botserver restart
# Visit http://localhost:8080/my-bot
```

### Production Server
```bash
scp -r my-bot.gbai/ server:~/botserver/templates/
ssh server "cd botserver && ./botserver restart"
```
### Deployment

### LXC Container
```bash
lxc file push my-bot.gbai/ container/app/templates/
```

No build step. No compilation. Just copy files.

## Multi-Bot Hosting

One BotServer runs multiple bots:

```
templates/
  support.gbai/       # support.example.com
  sales.gbai/         # sales.example.com
  internal.gbai/      # internal.example.com
  public.gbai/        # www.example.com
```

Each bot:
- Gets own URL endpoint
- Has isolated sessions
- Runs independently
- Shares infrastructure

## Template Inheritance

Bots can share common resources:

```
templates/
  _shared/
    knowledge/      # Shared documents
    tools/          # Shared functions
  bot1.gbai/
    bot1.gbot/
      config.csv  # includes: _shared
  bot2.gbai/
    bot2.gbot/
      config.csv  # includes: _shared
```

## Naming Conventions

### Required
- Folder must end with `.gbai`
- Subfolders must match: `botname.gbdialog`, `botname.gbkb`, etc.
- Main script must be `start.bas`

### Recommended
- Use lowercase with hyphens: `customer-service.gbai`
- Group related bots: `support-tier1.gbai`, `support-tier2.gbai`
- Version in folder name if needed: `chatbot-v2.gbai`

## Bootstrap Process

When BotServer starts:

```
![Template Deployment Flow](./assets/template-deployment-flow.svg)
```

Takes about 5-10 seconds per bot.

## Hot Reload

Change files while running:

```bash
# Edit script
vim templates/my-bot.gbai/my-bot.gbdialog/start.bas

# Reload just that bot
curl http://localhost:8080/api/admin/reload/my-bot

# Or restart everything
./botserver restart
```

## Package Size Limits

Default limits (configurable):
- Total package: 100MB
- Single document: 10MB  
- Number of files: 1000
- Script size: 1MB
- Collection count: 50

## Troubleshooting

**Bot not appearing?**
- Check folder ends with `.gbai`
- Verify subfolders match bot name
- Look for `start.bas` in `.gbdialog/`

**Documents not searchable?**
- Ensure files are in `.gbkb/` subfolder
- Check file format is supported
- Wait 30 seconds for indexing

**Scripts not running?**
- Validate BASIC syntax
- Check file has `.bas` extension
- Review logs for errors

## Best Practices

### Do's
✅ Keep packages under 50MB  
✅ Organize knowledge by topic  
✅ Use clear folder names  
✅ Test locally first  

### Don'ts
❌ Don't nest `.gbai` folders  
❌ Don't mix test/prod in same folder  
❌ Don't hardcode absolute paths  
❌ Don't store secrets in scripts  

## Summary

The `.gbai` architecture keeps bot development simple. No complex frameworks, no build systems, no deployment pipelines. Just organize your files in folders, and BotServer handles the rest. Focus on content and conversation, not configuration.

Next: Learn about [.gbdialog Dialogs](./gbdialog.md) for writing conversation scripts.