# simulanics/crossbasic architecture

> Architecture diagram of the GitHub repository simulanics/crossbasic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simulanics/crossbasic
- Repository: https://github.com/simulanics/crossbasic

## Overview

##### Project Type and Purpose
- This is a cross-platform compiler/VM toolchain (CrossBasic) plus a companion native compiler (xcompile), a web-based IDE, a rich plugin system, language-interop templates, and Xojo integration.
- It compiles Xojo-style scripts into bytecode for a custom VM, or into native executables via a separate tool, and supports dynamic plugins written in C++, Rust, Go, etc., using libffi.

##### High-Level Component Breakdown
A. Core CLI Tools
- crossbasic (cross-platform bytecode compiler + VM)
- xcompile (native code compiler)
- build scripts: build_crossbasic.bat/.sh, build_xcompile.bat/.sh
- Dependencies: libffi (FFI), libcurl (HTTP)
B. Plugin Subsystem (Microkernel Extensions)
- Plugins/… directories: each plugin has source + build scripts
- Interoperability/Plugin Language Templates: C#, C++, C, Go, Rust templates
- Runtime loader in crossbasic that scans “libs” folder via libffi
C. IDE Subsystem (MVC-style Web App)
- Server (CrossBasic-IDE/server.cpp)
- Build scripts: CrossBasic-IDE/build-64.bat/.sh
- Performance tests under ServerPerformanceTest
D. Xojo Integration
- Xojo Integration/…: connector code (.xojo_code, .xojo_project)
- Embeds CrossBasic as a library into Xojo projects
E. Support Scripts & Tests
- Scripts/*.xs: code-generator scripts for plugin bindings & tests
- runallscripts.bat/.sh to run integration tests

##### Relationships & Data Flows
- Developer writes CrossBasic code in IDE (Browser ←→ IDE Server over HTTP).
- IDE Server invokes crossbasic CLI or embeds its library to compile/execute scripts.
- crossbasic VM loads plugins at runtime from “libs” via libffi.
- Plugins implement features (JSON, DateTime, LLMConnection, GUI, etc.) and may call external APIs via libcurl.
- For native targets, crossbasic can hand off to xcompile or developer uses xcompile CLI directly.
- Build scripts orchestrate compiling core tools and each plugin in their own subfolder.
- Xojo projects use generated connector code to call CrossBasic engine as a library.

##### Architectural Patterns & Principles
- Microkernel/Plugin architecture: minimal core VM and extensible feature set via plugins
- MVC for the IDE: server component (controller & model) + static web UI (view)
- CLI-driven build/deploy pipeline (scripts automate building core and plugin artifacts)
- Language interoperability via libffi (decouples plugin language from core)

##### Final Recommendations
- Be exhaustive: capture core engine, compiler, plugin framework, IDE layers, build automation, interop, and external services.
- A high-level view and, if helpful, a zoomed-in section (e.g., plugin loading sequence).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer
    Developer["Developer\n(IDE Browser & CLI Shell)"]:::actor

    %% IDE Subsystem
    subgraph "IDE Subsystem"
        UI["Web UI\n(www/)"]:::ide
        Server["IDE Server\n(server.cpp)"]:::ide
        PerfTest["Performance Tests\n(ServerPerformanceTest/)"]:::ide
        BuildIDE["IDE Build Scripts\n(build-64.bat/.sh)"]:::scripts
    end

    %% Core Engine
    subgraph "Core Engine"
        CBC["crossbasic CLI"]:::core
        VM["VM & Bytecode Compiler"]:::core
        XComp["xcompile CLI"]:::core
        BuildCB["build_crossbasic.bat/.sh"]:::scripts
        BuildXC["build_xcompile.bat/.sh"]:::scripts
    end

    %% Plugin Subsystem
    subgraph "Plugin Subsystem"
        Loader["Plugin Loader"]:::core
        Plugins["Plugins"]:::plugin
    end

    %% Interop Layer
    subgraph "Interop Layer"
        FFI["libffi"]:::interop
        CURL["libcurl"]:::interop
    end

    %% Build & Deploy
    subgraph "Build & Deploy"
        Scripts["Build System & Scripts\n(build_plugins.bat/.sh,\nrunallscripts.bat/.sh)"]:::scripts
    end

    %% Interoperability Templates
    subgraph "Interoperability Templates"
        Templates["Plugin Language Templates\n(Interoperability/Plugin Language Templates/)"]:::interop
    end

    %% Xojo Integration
    subgraph "Xojo Integration"
        XojoRoot["Xojo Integration"]:::ide
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM APIs"]:::external
        FS["Filesystem"]:::external
        NET["Network"]:::external
    end

    %% Relationships
    Developer -->|HTTP Requests| Server
    Server -->|serves| UI
    Server -->|invokes compile| CBC
    Developer -->|CLI Commands| CBC
    Developer -->|CLI Commands| XComp

    CBC -->|compiles bytecode| VM
    CBC -->|loads via libffi| Loader
    Loader -->|discovers| Plugins
    Plugins -->|uses FFI| FFI
    Plugins -->|calls external APIs| CURL
    Plugins -->|HTTP calls| NET
    Plugins -->|uses external| LLM
    VM -->|I/O| FS

    CBC -->|native handoff| XComp

    Scripts -->|build core| CBC
    Scripts -->|build plugins| Plugins

    Templates -->|generate bindings for| Plugins

    XojoRoot -->|embeds library| CBC

    %% Click Events
    click UI "https://github.com/simulanics/crossbasic/tree/main/CrossBasic-IDE/www/"
    click Server "https://github.com/simulanics/crossbasic/blob/main/CrossBasic-IDE/server.cpp"
    click PerfTest "https://github.com/simulanics/crossbasic/tree/main/CrossBasic-IDE/ServerPerformanceTest/"
    click BuildIDE "https://github.com/simulanics/crossbasic/blob/main/CrossBasic-IDE/build-64.bat"
    click CBC "https://github.com/simulanics/crossbasic/blob/main/crossbasic.cpp"
    click CBC "https://github.com/simulanics/crossbasic/blob/main/crossbasic.rc"
    click BuildCB "https://github.com/simulanics/crossbasic/blob/main/build_crossbasic.bat"
    click BuildCB "https://github.com/simulanics/crossbasic/blob/main/build_crossbasic.sh"
    click XComp "https://github.com/simulanics/crossbasic/blob/main/xcompile.cpp"
    click XComp "https://github.com/simulanics/crossbasic/blob/main/xcompile.rc"
    click BuildXC "https://github.com/simulanics/crossbasic/blob/main/build_xcompile.bat"
    click BuildXC "https://github.com/simulanics/crossbasic/blob/main/build_xcompile.sh"
    click Scripts "https://github.com/simulanics/crossbasic/blob/main/build_plugins.bat"
    click Scripts "https://github.com/simulanics/crossbasic/blob/main/build_plugins.sh"
    click Scripts "https://github.com/simulanics/crossbasic/blob/main/runallscripts.bat"
    click Scripts "https://github.com/simulanics/crossbasic/blob/main/runallscripts.sh"
    click Plugins "https://github.com/simulanics/crossbasic/tree/main/Plugins/"
    click Templates "https://github.com/simulanics/crossbasic/tree/main/Interoperability/Plugin Language Templates/"
    click XojoRoot "https://github.com/simulanics/crossbasic/tree/main/Xojo Integration/"

    %% Styles
    classDef actor fill:#eef,stroke:#333,stroke-width:1px
    classDef ide fill:#fdd,stroke:#f66,stroke-width:1px
    classDef core fill:#ddf,stroke:#66f,stroke-width:1px
    classDef plugin fill:#dfd,stroke:#6c6,stroke-width:1px
    classDef interop fill:#fdf,stroke:#c6c,stroke-width:1px
    classDef scripts fill:#eee,stroke:#999,stroke-width:1px
    classDef external fill:#ffe,stroke:#cc0,stroke-width:1px
```
