# bigsweetpotatostudio/hyperchat architecture

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

- Interactive diagram: https://gitdiagram.com/bigsweetpotatostudio/hyperchat
- Repository: https://github.com/bigsweetpotatostudio/hyperchat

## Overview

##### Main Components and Their Roles
- Desktop Client (Electron):
- Located in the “electron” folder.
- Contains entry points like main process scripts (main.mts, preload.ts) and polyfills.
- Handles system-level operations, native API integrations, and packaging for platforms (Windows, Mac, Linux).
- Manages build configurations, notarization processes, and platform-specific resources (mac entitlements, notarize.js).
- Web Client:
- Housed in the “web” directory.
- Built as a React/TypeScript application (look in files like App.tsx, router.tsx, pages/*).
- Provides the browser-based UI experience.
- Contains its own configuration (webpack, tailwind, etc.) and testing components.
- MCP (Modular Control/Plugin) Infrastructure:
- Found within several subdirectories under electron/ts/mcp and web/src/common/mcp.ts.
- Facilitates the installation and management of third-party plugins, extension marketplace protocols, and agent interactions.
- Manages server communications for special functionalities like task execution (e.g., terminal integration, knowledge base servers).
- Shared/Common Modules:
- The “common” folder and cross-cutting modules in both Electron and Web (e.g., common/data.ts, shared utilities in electron/ts/common) provide reusable business logic, utility functions, and data models.
- CI/CD and Deployment Tools:
- GitHub workflows under “.github/workflows” show the continuous integration pipelines (building, testing, publishing).
- Docker configuration files located in the “docker” folder for both Electron and no-electron (CLI-only) deployments.
- External Integrations:
- Integration with various language model APIs (as described in the README) and external services (WebDAV, web scraping, etc.).
- The README emphasizes usage of uv & nodejs, so system requirements and toolchains are part of the overall ecosystem.

##### Relationships and Interactions
- How the UI clients communicate with the MCP servers or service modules responsible for handling commands and interacting with external LLM APIs.
- CI/CD pipelines feeding into the build/deployment procedures (Docker, GitHub Actions).
- Data flow: user interactions at the UI (Electron or Web) → message service/command execution modules → MCP integration → LLM API calls to various providers.
- Integrations with external services (e.g., WebDAV for synchronization, external API endpoints for LLMs) as separate entities interfaced via clearly defined APIs.

##### Architectural Patterns and Design Principles
- Layered Architecture: Separate presentation layers (Electron UI, Web UI) from service layers (MCP servers, common processing modules) and infrastructure layers (Docker, GitHub workflows).
- Modular Design: Highlight how the MCP plugin marketplace enables dynamic extension of functionalities, making it a highly flexible system.
- Cross-Platform Consistency: Show that the system is designed to handle both desktop and web variants without redundancy by reusing core services.
- Dependency Management: Indicate the use of Node.js, npm, and build tools (webpack, tailwind, etc.) that tie the system together.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Electron Desktop Client"
        E1["Main Process (main.mts)"]:::client
        E2["Preload Script (preload.ts)"]:::client
        E3["Build Scripts (build)"]:::client
        E4["Webpack Configuration (webpack.config.js)"]:::client
    end

    subgraph "Web Client"
        W1["App Component (App.tsx)"]:::client
        W2["Router Configuration (router.tsx)"]:::client
        W3["Pages"]:::client
    end

    subgraph "Common Libraries"
        C1["Common Utilities (data.ts)"]:::common
        C2["Electron Shared"]:::common
        C3["Web Shared"]:::common
    end

    subgraph "MCP Services"
        M1["Electron MCP"]:::service
        M2["Web MCP"]:::service
    end

    subgraph "LLM API & External Services"
        L1["Electron Integrations"]:::external
        L2["Web Integrations"]:::external
    end

    subgraph "CI/CD & Deployment"
        P1["GitHub Workflows"]:::infra
        P2["Docker Configuration"]:::infra
    end

    %% Data Flow and Dependencies
    E1 -->|"uses"| C1
    W1 -->|"uses"| C1

    C1 -->|"integrates"| M1
    C1 -->|"integrates"| M2

    M1 -->|"calls"| L1
    M2 -->|"calls"| L2

    P1 -->|"builds"| P2
    P2 -->|"deploys"| E1
    P2 -->|"deploys"| W1

    %% Additional UI interactions
    E2 --- M1
    W2 --- M2

    %% styles
    classDef client fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef service fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef common fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef infra fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;

    %% Click Events
    click E1 "https://github.com/bigsweetpotatostudio/hyperchat/blob/alpha/electron/ts/main.mts"
    click E2 "https://github.com/bigsweetpotatostudio/hyperchat/blob/alpha/electron/ts/preload.ts"
    click E3 "https://github.com/bigsweetpotatostudio/hyperchat/tree/alpha/electron/build"
    click E4 "https://github.com/bigsweetpotatostudio/hyperchat/blob/alpha/electron/webpack.config.js"

    click W1 "https://github.com/bigsweetpotatostudio/hyperchat/blob/alpha/web/src/App.tsx"
    click W2 "https://github.com/bigsweetpotatostudio/hyperchat/blob/alpha/web/src/router.tsx"
    click W3 "https://github.com/bigsweetpotatostudio/hyperchat/tree/alpha/web/pages/"

    click M1 "https://github.com/bigsweetpotatostudio/hyperchat/tree/alpha/electron/ts/mcp"
    click M2 "https://github.com/bigsweetpotatostudio/hyperchat/blob/alpha/web/src/common/mcp.ts"

    click C1 "https://github.com/bigsweetpotatostudio/hyperchat/blob/alpha/common/data.ts"
    click C2 "https://github.com/bigsweetpotatostudio/hyperchat/tree/alpha/electron/ts/common"
    click C3 "https://github.com/bigsweetpotatostudio/hyperchat/tree/alpha/web/src/common"

    click P1 "https://github.com/bigsweetpotatostudio/hyperchat/tree/alpha/.github/workflows"
    click P2 "https://github.com/bigsweetpotatostudio/hyperchat/tree/alpha/docker"

    click L1 "https://github.com/bigsweetpotatostudio/hyperchat/tree/alpha/electron/ts/langchain"
    click L2 "https://github.com/bigsweetpotatostudio/hyperchat/blob/alpha/web/src/common/openai.ts"
```
