# saisandeepvaddi/ten-hands architecture

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

- Interactive diagram: https://gitdiagram.com/saisandeepvaddi/ten-hands
- Repository: https://github.com/saisandeepvaddi/ten-hands

## Overview

##### Project’s Major Building Blocks
- Desktop Application (Electron): The “app/electron” folder contains the Electron main process code along with related modules (such as IPC, tray, global-hot-keys, preload, updates, etc.). This layer handles the desktop integration, window management, and experiences like menus and system tray interactions.
- Web/Browser UI: The “ui” folder is dedicated to the frontend with React components, supporting testing (Cypress, Jest) and service workers. This is for the web version of the application where users can interact with their tasks in a browser.
- CLI Tool: The “cli” directory contains a command-line interface tool (written in Node/TypeScript) that can be globally installed. Its purpose is to start the app (e.g., “ten-hands start”) and interact with the other components.
- Browser Extension: The “extension” directory holds code for a browser extension (manifest, background scripts, content scripts, options, popup) that integrates with the core functionality, likely to extend usability and offer in-browser quick access.
- Shared Components and Configurations: Several utility and configuration files are spread across “app/shared”, along with global config files (like ESLint, Prettier, tsconfig, etc.), which are part of the project’s development ecosystem.
- Persistence: The presence of a “db.json” file suggests that some form of lightweight JSON-based database or configuration persistence is used to store state/projects.

##### Relationships and Interactions
- The Electron part (desktop) acts as a shell that manages windows, menus, and system tray. It invokes the backend server (either via IPC or by making HTTP/WebSocket calls) to manage projects and tasks.
- The server, likely running as a Node/Express “app/server” instance, exposes REST endpoints or WebSocket interfaces. Its controllers and services coordinate command execution, project handling, and job/task management.
- The UI (React application in “ui”) communicates with the backend server. In the desktop version, communication may occur through inter-process communication (IPC) between renderer processes and the main process.
- The CLI tool (“cli”) provides a simple way to launch or interact with the core functionality (for example, starting the server or interfacing with tasks programmatically).
- The browser extension integrates via background scripts and a popup UI (with shared services for messaging) to offer quick access to command-line tasks directly from within the browser.
- All components share a common configuration (look for “config.ts” under “app/shared” and the supported “config.json” in the user’s home directory), which is crucial to align the behavior across desktop, CLI, UI, and extension.

##### Architectural Patterns and Design Principles
- Layered Architecture: There is a clear separation between presentation/UI (both web and Electron renderer), business logic (server controllers/services), and lower-level utilities.
- Client–Server and IPC Communication: The design supports different types of clients (Electron, web browser, CLI, and extension) that interact with the centralized back end through HTTP/WebSocket or Electron IPC.
- Modularization: The project is split into logically distinct directories (electron, server, ui, cli, extension), indicating a modular design where each component can be developed and potentially deployed separately.

##### Including Relevant Technologies and Frameworks
- Electron for Desktop application
- Node.js/Express for the back end
- React (and its ecosystem) for the web UI
- TypeScript as the primary development language for many components
- CLI tool built with Node
- Testing frameworks such as Jest and Cypress for UI and integration testing
- Potential use of WebSocket for real-time task/job status (as seen in the “socket.ts” in “app/server/services”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Desktop Application (Electron)
    subgraph "Desktop Application (Electron)"
        EMain["Main Process<br/>(Electron)"]:::desktop
        ERenderer["Renderer Process<br/>(Electron)"]:::desktop
        EMain -->|"IPC"| ERenderer
    end

    %% Web/Browser UI
    UI["Web UI<br/>(React/TypeScript)"]:::web

    %% Browser Extension
    Ext["Browser Extension"]:::extension

    %% CLI Tool
    CLI["CLI Tool<br/>(Node/TypeScript)"]:::cli

    %% Backend Server
    Server["Backend Server<br/>(Node/Express)"]:::server

    %% Shared Components & Configurations
    SC["Shared Components & Config"]:::shared

    %% Persistence Layer
    DB["DB.json (Persistence)"]:::database

    %% Interactions between Client Components and Backend Server
    ERenderer ---|"HTTP/WebSocket"| Server
    UI ---|"HTTP/WebSocket"| Server
    Ext ---|"BackgroundMessaging"| Server
    CLI ---|"APICalls"| Server

    %% Backend uses Shared Config and Persists Data
    Server ---|"Uses"| SC
    Server ---|"PersistsIn"| DB

    %% Click Events
    click EMain "https://github.com/saisandeepvaddi/ten-hands/tree/main/app/electron"
    click ERenderer "https://github.com/saisandeepvaddi/ten-hands/tree/main/app/electron"
    click Server "https://github.com/saisandeepvaddi/ten-hands/tree/main/app/server"
    click UI "https://github.com/saisandeepvaddi/ten-hands/tree/main/ui"
    click Ext "https://github.com/saisandeepvaddi/ten-hands/tree/main/extension"
    click CLI "https://github.com/saisandeepvaddi/ten-hands/tree/main/cli"
    click SC "https://github.com/saisandeepvaddi/ten-hands/tree/main/app/shared"
    click DB "https://github.com/saisandeepvaddi/ten-hands/blob/main/db.json"

    %% Styles
    classDef desktop fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef web fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef extension fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef cli fill:#FFF59D,stroke:#FBC02D,stroke-width:2px;
    classDef server fill:#FFCCBC,stroke:#EF6C00,stroke-width:2px;
    classDef shared fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;
    classDef database fill:#FFECB3,stroke:#FFA000,stroke-width:2px;
```
