How saisandeepvaddi/ten-hands works
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”)