# badboysm890/claraverse architecture

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

- Interactive diagram: https://gitdiagram.com/badboysm890/claraverse
- Repository: https://github.com/badboysm890/claraverse

## Overview

##### Project Type & Purpose
- The project is a full-stack, cross-platform desktop application that leverages a web-based frontend (built using React in the “src” directory) integrated with an Electron shell for desktop distribution. It’s designed to serve as an AI assistant, an intelligent agent builder (via a node-based editor), an image generator (using open-source models like Stable Diffusion with ComfyUI), and also includes an image gallery.
- It emphasizes local execution (zero telemetry), connecting to Ollama services on “localhost” for model inference, and allows users to build custom intelligent agents.

##### Main Components
a. Frontend/UI:
- Located primarily in the “src” directory, containing React components for different modules – Assistant, Image Generation, Agent Builder, Gallery, etc.
- Additional UI parts like components for the node editor (located under “src/components/appcreator_components” and “src/components/appcreator_components/nodes”) represent the agent builder’s interactive functionalities.

b. Desktop Shell (Electron):
- The “electron” directory holds Electron-specific scripts (main.cjs, preload.cjs, pythonBackend.cjs, etc.), which package the web app into a native desktop application.
- Includes services for splash screen, update service, and integration with the Python backend.

c. Python Backend:
- The “py_backend” directory contains Python files (e.g., main.py, Speech2Text.py, ragDbClara.py), an SQLite “app.db”, and dependencies (requirements.txt).
- This backend likely handles compute-intensive tasks (like speech-to-text and perhaps other integrations) and provides a local API that the Electron process can call.

d. Node-Based Execution & Services:
- The “src/nodeExecutors” directory implements various execution logic for nodes in the agent builder (e.g., various nodes like ApiCallExecutor, BaseLlmExecutor, etc.).
- “src/services” contains utilities (e.g., AppStore and API services), database interactions (indexedDB), and clients for external services like Ollama and ComfyUI.

e. Deployment & Infrastructure:
- Docker-related files (Dockerfile, docker-publish.sh, nginx.conf) indicate containerization for deployment which includes a web version and local Docker instance.
- Additional scripts for build, cleanup, and notarization (e.g., installer.nsh, notarize.cjs, setup-notarize.sh) are present for platform-specific deployment.

##### Relationships & Interactions
- The Electron main process (in the “electron” folder) acts as the bridge between the native desktop shell and the web application's UI components.
- The UI components (from “src”) interact with backend services, either directly (if using REST or internal modules) or indirectly via the node execution modules.
- The Python backend is integrated with the Electron process (as seen in “electron/pythonBackend.cjs”) to perform tasks like speech-to-text or interfacing with specific AI model utilities.
- The system also connects to an external local Ollama endpoint (default “http://localhost:11434”), as configured in settings and accessed via the Ollama client in “src/utils/OllamaClient.ts”.
- Docker deployment is supported; therefore, the whole stack may also be encapsulated within a container for Linux and Windows deployments.

##### Architectural Patterns & Technologies
- Modular separation is evident: clear separation between the Electron wrapper, the React UI layers, the Python backend for processing, and the node-based execution engine for building agents.
- Use of client-side state management (via React context and hooks in “src/context” and “src/hooks”) and a tightly integrated modular design for each feature.
- Technologies include Electron (for desktop app), React (frontend UI), Node.js (for server-like operations and execution modules), Python (backend processing tasks), Docker for containerization, and integration with external open-source AI models (via Ollama and ComfyUI).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Desktop Application"
        DS["Electron Shell (Desktop)"]:::electron
        FE["Frontend UI (React)"]:::frontend
        subgraph "Agent Builder UI"
            AB["Node Editor UI (Agent Builder)"]:::frontend
        end
        DS -->|"IPC"| FE
        FE -->|"Contains"| AB
    end

    DS -->|"Bridges"| BE["Python Backend"]:::backend
    FE -->|"Triggers"| NE["Node-Based Execution Engine"]:::nodeExec
    FE -->|"Uses"| SV["Services & API Utilities"]:::services
    SV -->|"Calls"| EX["Ollama Endpoint (http://localhost:11434)"]:::external
    AB -->|"Executes via"| NE
    BE -->|"REST/API"| EX

    subgraph "Deployment & Infrastructure"
        DP["Deployment Container (Docker & Scripts)"]:::deployment
    end
    DP -->|"Encapsulates"| DS

    %% Click Events
    click FE "https://github.com/badboysm890/claraverse/tree/main/src"
    click AB "https://github.com/badboysm890/claraverse/tree/main/src/components/appcreator_components"
    click AB "https://github.com/badboysm890/claraverse/tree/main/src/components/appcreator_components/nodes"
    click DS "https://github.com/badboysm890/claraverse/tree/main/electron"
    click BE "https://github.com/badboysm890/claraverse/tree/main/py_backend"
    click NE "https://github.com/badboysm890/claraverse/tree/main/src/nodeExecutors"
    click SV "https://github.com/badboysm890/claraverse/tree/main/src/services"
    click DP "https://github.com/badboysm890/claraverse/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#C1E1FF,stroke:#1f78b4,stroke-width:2px;
    classDef electron fill:#FFE0B3,stroke:#ffad33,stroke-width:2px;
    classDef backend fill:#FFCCCC,stroke:#e60000,stroke-width:2px;
    classDef nodeExec fill:#D5F5E3,stroke:#27ae60,stroke-width:2px;
    classDef services fill:#F9E79F,stroke:#f1c40f,stroke-width:2px;
    classDef deployment fill:#D2B4DE,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#c0392b,stroke-width:2px;
```
