botserver/docs/src/chapter-07-gbapp/README.md

gbapp: Virtual Crates Architecture

This chapter explains how BotServer uses the gbapp concept as virtual crates within the src/ directory, elegantly mapping the old package system to the new Rust architecture.

The gbapp Evolution: From Packages to Virtual Crates

Historical Context (Node.js Era)

In previous versions, .gbapp packages were external Node.js modules that extended BotServer functionality through a plugin system.

Current Architecture (Rust Era)

The .gbapp concept now lives as virtual crates inside src/:

• Virtual Crates: Each gbapp is a module inside src/ (like src/core, src/basic, src/channels)
• Same Mental Model: Developers familiar with the old system can think of each directory as a "package"
• Native Performance: All code compiles into a single optimized binary
• Contribution Path: Add new gbapps by creating modules in src/

How gbapp Virtual Crates Work

src/
├── core/           # core.gbapp (virtual crate)
├── basic/          # basic.gbapp (BASIC interpreter)
├── channels/       # channels.gbapp (communication)
├── storage/        # storage.gbapp (persistence)
├── auth/           # auth.gbapp (authentication)
├── llm/            # llm.gbapp (AI integration)
└── your_feature/   # your_feature.gbapp (your contribution!)

Each directory is conceptually a gbapp - a self-contained module that contributes functionality to the whole.

Why This Change?

1. Simplicity: One cohesive codebase instead of fragmented extensions
2. Performance: Native Rust performance without extension overhead
3. Reliability: Thoroughly tested core features vs. variable-quality plugins
4. BASIC Power: BASIC + LLM combination eliminates need for custom code
5. Maintenance: Easier to maintain one strong core than many extensions

Contributing New Keywords

Contributing a New gbapp Virtual Crate

To add functionality, create a new gbapp as a module in src/:

// src/your_feature/mod.rs - Your gbapp virtual crate
pub mod keywords;
pub mod services;
pub mod models;

// src/your_feature/keywords/mod.rs
use crate::shared::state::AppState;
use rhai::Engine;

pub fn register_keywords(engine: &mut Engine, state: Arc<AppState>) {
    engine.register_fn("YOUR KEYWORD", move |param: String| -> String {
        // Implementation
        format!("Result: {}", param)
    });
}

This maintains the conceptual model of packages while leveraging Rust's module system.

Contribution Process for gbapp Virtual Crates

1. Fork the BotServer repository
2. Create your gbapp module in src/your_feature/
3. Structure it like existing gbapps (core, basic, etc.)
4. Test thoroughly with unit and integration tests
5. Document in the appropriate chapter
6. Submit PR describing your gbapp's purpose

Example structure for a new gbapp:

src/analytics/          # analytics.gbapp
├── mod.rs             # Module definition
├── keywords.rs        # BASIC keywords
├── services.rs        # Core services
├── models.rs          # Data models
└── tests.rs           # Unit tests

Adding New Components

Components are features compiled into BotServer via Cargo features:

Current Components in Cargo.toml

[features]
# Core features
chat = []           # Chat functionality
drive = []          # Storage system
tasks = []          # Task management
calendar = []       # Calendar integration
meet = []           # Video meetings
mail = []           # Email system

# Enterprise features
compliance = []     # Compliance tools
attendance = []     # Attendance tracking
directory = []      # User directory

Adding a New Component

1. Define Feature in Cargo.toml:

[features]
your_feature = ["dep:required_crate"]

2. Implement in appropriate module:

#[cfg(feature = "your_feature")]
pub mod your_feature {
    // Implementation
}

3. Register in installer.rs:

fn register_your_feature(&mut self) {
    self.components.insert(
        "your_feature",
        Component {
            name: "Your Feature",
            description: "Feature description",
            port: None,
            setup_required: false,
        },
    );
}

Understanding the gbapp → Virtual Crate Mapping

The transition from Node.js packages to Rust modules maintains conceptual familiarity:

Old (Node.js)	New (Rust)	Location	Purpose
core.gbapp	core module	src/core/	Core engine functionality
basic.gbapp	basic module	src/basic/	BASIC interpreter
whatsapp.gbapp	channels::whatsapp	src/channels/whatsapp/	WhatsApp integration
kb.gbapp	storage::kb	src/storage/kb/	Knowledge base
custom.gbapp	custom module	src/custom/	Your contribution

Creating Private gbapp Virtual Crates

For proprietary features, you can still create private gbapps:

// Fork BotServer, then add your private gbapp
// src/proprietary/mod.rs
#[cfg(feature = "proprietary")]
pub mod my_private_feature {
    // Your private implementation
}

Then in Cargo.toml:

[features]
proprietary = []

This keeps your code separate while benefiting from core updates.

Benefits of the Virtual Crate Approach

1. Familiar Mental Model: Developers understand "packages"
2. Clean Separation: Each gbapp is self-contained
3. Easy Discovery: All gbapps visible in src/
4. Native Performance: Everything compiles together
5. Type Safety: Rust ensures interfaces are correct

Real Examples of gbapp Virtual Crates in src/

src/
├── core/               # Core gbapp - Bootstrap, package manager
│   ├── mod.rs
│   ├── bootstrap.rs
│   └── package_manager/
│
├── basic/              # BASIC gbapp - Interpreter and keywords  
│   ├── mod.rs
│   ├── interpreter.rs
│   └── keywords/
│       ├── mod.rs
│       ├── talk.rs
│       ├── hear.rs
│       └── llm.rs
│
├── channels/           # Channels gbapp - Communication adapters
│   ├── mod.rs
│   ├── whatsapp.rs
│   ├── teams.rs
│   └── email.rs
│
└── analytics/          # Your new gbapp!
    ├── mod.rs
    ├── keywords.rs     # ADD ANALYTICS, GET METRICS
    └── services.rs     # Analytics engine

Development Environment

System Requirements

• Disk Space: 8GB minimum for development
• RAM: 8GB recommended
• Database: Any SQL database (abstracted)
• Storage: Any S3-compatible storage (abstracted)

No Brand Lock-in

BotServer uses generic terms:

• ❌ PostgreSQL → ✅ "database"
• ❌ MinIO → ✅ "drive storage"
• ❌ Qdrant → ✅ "vector database"
• ❌ Redis → ✅ "cache"

This ensures vendor neutrality and flexibility.

Security Best Practices

Regular Audits

Run security audits regularly:

cargo audit

This checks for known vulnerabilities in dependencies.

Secure Coding

When contributing:

• Validate all inputs
• Use safe Rust patterns
• Avoid unsafe blocks
• Handle errors properly
• Add security tests

Testing Your Contributions

Unit Tests

#[cfg(test)]
mod tests {
    #[test]
    fn test_keyword() {
        // Test your keyword
    }
}

Integration Tests

#[tokio::test]
async fn test_feature() {
    // Test feature integration
}

BASIC Script Tests

' test_script.bas
result = YOUR KEYWORD "test"
IF result != "expected" THEN
    TALK "Test failed"
ELSE
    TALK "Test passed"
END IF

Documentation Requirements

All contributions must include:

1. Keyword Documentation in Chapter 6
2. Architecture Updates if structural changes
3. API Documentation for new endpoints
4. BASIC Examples showing usage
5. Migration Guide if breaking changes

Performance Considerations

Benchmarking

Before submitting:

cargo bench

Profiling

Identify bottlenecks:

cargo flamegraph

Community Guidelines

What We Accept

✅ New BASIC keywords that benefit many users
✅ Performance improvements
✅ Bug fixes with tests
✅ Documentation improvements
✅ Security enhancements

What We Don't Accept

❌ Vendor-specific integrations (use generic interfaces)
❌ Extensions that bypass BASIC
❌ Features achievable with existing keywords
❌ Undocumented code
❌ Code without tests

The Power of BASIC + LLM

Remember: In 2025, 100% BASIC/LLM applications are reality. Before adding a keyword, consider:

1. Can this be done with existing keywords + LLM?
2. Will this keyword benefit multiple use cases?
3. Does it follow the BASIC philosophy of simplicity?

Example: No Custom Code Needed

Instead of custom integration code:

' Everything in BASIC
data = GET "api.example.com/data"
processed = LLM "Process this data: " + data
result = FIND "table", "criteria=" + processed
SEND MAIL user, "Results", result

Future Direction

BotServer's future is:

• Stronger Core: More powerful built-in keywords
• Better LLM Integration: Smarter AI capabilities
• Simpler BASIC: Even easier scripting
• Community-Driven: Features requested by users

How to Get Started

1. Fork the repository
2. Read existing code in src/basic/keywords/
3. Discuss your idea in GitHub Issues
4. Implement following the patterns
5. Test thoroughly
6. Document completely
7. Submit PR with clear explanation

Summary

The .gbapp concept has elegantly evolved from external Node.js packages to virtual crates within src/. This approach:

• Preserves the mental model developers are familiar with
• Maps perfectly to Rust's module system
• Encourages contribution by making the structure clear
• Maintains separation while compiling to a single binary

Each directory in src/ is effectively a gbapp - contribute by adding your own! With BASIC + LLM handling the complexity, your gbapp just needs to provide the right keywords and services.

See Also

• Philosophy - The gbapp philosophy: Let machines do machine work
• Architecture - System architecture
• Building - Build process
• Custom Keywords - Keyword implementation
• Services - Core services
• Chapter 6: BASIC Reference - BASIC language
• Chapter 9: API - API documentation

---