# kkharji/xbase architecture

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

- Interactive diagram: https://gitdiagram.com/kkharji/xbase
- Repository: https://github.com/kkharji/xbase

## Overview

##### Project Type and Purpose
- XBase is a development environment designed as an alternative to Xcode. Its purpose is to allow users to build, watch, and run Xcode projects and Swift packages from within their preferred editors.
- It supports multiple platforms (iOS, watchOS, tvOS), provides real-time logging, and integrates with language servers (such as sourcekit-lsp) for features like auto-completion and navigation.
- The project targets both Neovim (via Lua scripts) and VSCode (via TypeScript), while its core is written in Rust.

##### Analysis of the File Structure
- The top-level directories include configuration files (e.g., .github, Cargo.toml, Makefile, LICENSE), multiple source directories (src, crates, lua, vscode), and tooling (syntax, dev.md).
- The Rust ecosystem is evident from the Cargo-related files and directories:
- The main core is in the src directory (with submodules like broadcast, runner, runtime, server, watcher, etc.).
- There is a separate crate (crates/sourcekit-helper) that aids in setting up or interfacing with the language service (sourcekit-lsp).
- There are integration layers:
- Lua scripts in the lua directory (and corresponding files in vscode/xbase) provide the Neovim plugin functionality.
- The vscode folder holds TypeScript files that set up the VSCode extension, mirroring functionality provided in the Lua layer.
- Additional project generators (in src/project) indicate support for Xcode project generation through tools like XcodeGen and Tuist.

##### Key Components
a. Core Rust Daemon/Server:
- Main server binary (src/main.rs) responsible for coordinating the build, watch, and run operations.
- Submodules (broadcast, runner, runtime, server, watcher, etc.) that handle messaging, device communication, file watching, and process orchestration.
b. SourceKit Helper:
- A dedicated helper implemented in the separate crate (crates/sourcekit-helper) to interact with sourcekit-lsp for code-completion and navigation.
c. Editor Integration Layers:
- Neovim:
◦ Lua integration in the lua directory (e.g., lua/xbase) for configuration, statusline updates, command handling, and communication with the daemon.
- VSCode:
◦ The VSCode extension implemented via TypeScript files (inside the vscode directory) providing similar integration as the Neovim plugins.
d. Project Generation Modules:
- The modules under src/project responsible for handling different project types (barebone, swift, tuist, xcodegen) should be depicted to show how they automatically generate or update Xcode projects.
e. External Dependencies and Tools:

##### Relationships and Interactions
- An interaction between the Daemon/Server and the SourceKit Helper, indicating that when auto-completion or code navigation is needed, the daemon invokes sourcekit-lsp functionalities.
- The broadcast module communicates real-time logs and messages to the client layers.
- The runner module interacts with simulator components (or real devices) for launching builds or tests.
- The watcher module tracks file changes and triggers project regeneration or rebuild tasks.
- Optionally, demonstrate data flows regarding project configuration (project.yml, Package.swift, etc.) that feed into the project generation modules.

##### Architectural Patterns and Design Principles
- Modular Design: The system is divided into clear modules (server, runner, project generator, etc.) that communicate via well-defined interfaces.
- Client-Server Interaction: Both Neovim and VSCode act as clients sending commands to a centralized server daemon.
- Extensibility: The existence of different project generators (XcodeGen, Tuist) and distinct integration layers highlights a plugin-friendly, extensible design.
- Lightweight & Reactive: Emphasize the “zero footprint” and event-driven nature provided by the watcher and broadcast components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Editor Integrations"
        A["Neovim Plugin (Lua)\n(vim script integration, configuration & status updates)"]:::client
        B["VSCode Extension (TypeScript)\n(command handling, UI integration)"]:::client
    end

    C["Core Rust Daemon/Server\n(src/main.rs\nCoordinating build, watch, run)"]:::server

    A -->|"sends commands\n(build, run, watch)"| C
    B -->|"sends commands\n(build, run, watch)"| C

    subgraph "Internal Server Modules"
        D["Broadcast Module\n(real-time logging & messaging)"]:::module
        E["Runner Module\n(launches simulator/device processes)"]:::module
        F["Watcher Module\n(monitors file changes & triggers regenerations)"]:::module
        G["Other Modules\n(runtime, server coordination)"]:::module
    end

    C --> D
    C --> E
    C --> F
    C --> G

    E -->|"launches"| H["Simulator/Devices\n(physical & simulated targets)"]:::external

    F -->|"triggers build updates"| I["Project Generators\n(XcodeGen, Tuist modules)"]:::module
    I -->|"updates"| J["Project Configurations\n(project.yml, Package.swift)"]:::external

    C -->|"integrates with"| K["SourceKit Helper (Rust Crate)\n(crucial for auto-completion & navigation)"]:::server
    K -->|"invokes"| L["sourcekit-lsp\n(language server for Swift)"]:::external

    subgraph "Project Structure & Versions"
        M["Configuration Files\n(.github, Cargo.toml, Makefile, LICENSE)"]:::external
        N["Source Directories\n(src, crates, lua, vscode)"]:::external
        O["Version Dependencies\n(Rust ^1.60, Neovim ^0.7)"]:::external
    end

    %% Relationships from project structure (informational)
    C --- N
    K --- N
    I --- N
    M --- O

    click C "https://github.com/kkharji/xbase/blob/master/src/main.rs"
    click K "https://github.com/kkharji/xbase/tree/master/crates/sourcekit-helper"
    click A "https://github.com/kkharji/xbase/tree/master/lua/xbase"
    click B "https://github.com/kkharji/xbase/tree/master/vscode/xbase"
    click I "https://github.com/kkharji/xbase/tree/master/src/project"

    classDef client fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef server fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef module fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;
```
