# edwinjosephshiju/localcel.cpp-aio architecture

> Architecture diagram of the GitHub repository edwinjosephshiju/localcel.cpp-aio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edwinjosephshiju/localcel.cpp-aio
- Repository: https://github.com/edwinjosephshiju/localcel.cpp-aio

## Overview

1. **Overall shape**
   - This repository is a native **C++20 / Win32 desktop application** for managing local server apps and sharing them externally.
   - The architecture is intentionally split into modules under `src/`, with a separate **all-in-one amalgamation** file for simpler compilation and distribution.

2. **Startup and top-level orchestration**
   - `src/main.cpp` is the application entry point.
   - The runtime flow appears to start the **UI**, then delegate to the core managers for workspace loading, process control, networking, and deployment actions.

3. **UI boundary: `src/ui/WindowsUI.*`**
   - The UI layer is a **pure Win32** implementation, not Qt or web-based.
   - It owns the desktop windowing concerns: rendering, theming, dark mode, and Windows 11-style visual polish.
   - This layer should be treated as the presentation boundary that invokes core services, rather than containing business logic.

4. **Core workspace and configuration: `src/core/AppManager.*`**
   - `AppManager` is the central application-state module.
   - It handles **workspace loading**, **app configuration**, JSON-driven settings, and filesystem orchestration.
   - This is likely the main source of truth for what local app/server definitions exist and how they are persisted.

5. **Core process lifecycle: `src/core/ProcessManager.*`**
   - `ProcessManager` manages the lifecycle of **Node.js server processes** and **Cloudflare tunnel processes**.
   - The README highlights use of **Windows Job Objects** for cleanup, which is important architecturally: child processes are grouped so the app can terminate them reliably as a unit.
   - This module is the operational boundary between the GUI and the OS process layer.

6. **Core utilities: `src/core/Utils.*`**
   - `Utils` provides cross-cutting helpers such as UTF-8 conversion, process execution, and JSON parsing.
   - This is a support layer used by several subsystems to avoid duplicating OS and data-format glue code.

7. **Networking / tunneling: `src/network/CloudflareManager.*`**
   - `CloudflareManager` encapsulates **Cloudflare Tunnel (`cloudflared`)** authentication and lifecycle management.
   - It acts as the network-sharing layer that turns a local server into something externally reachable.
   - From an architecture perspective, this is the outbound exposure boundary: local app traffic is bridged to Cloudflare through a managed tunnel process.

8. **Deployment / GitHub publishing: `src/deploy/GitManager.*`**
   - `GitManager` orchestrates **GitHub repository creation** and **GitHub Pages deployment** using the `git` and `gh` command-line tools.
   - This is a separate operational path from tunneling: instead of exposing a live local service, it packages and publishes content through GitHub tooling.

9. **Dependency provisioning: `src/deps/*`**
   - `DependencyManager` is a polymorphic installer/detector for external tools such as Git, GitHub CLI, and Cloudflare tooling.
   - Platform-specific implementations exist for **Windows, Linux, macOS, and Android**, though the README emphasizes Windows as the primary runtime.
   - This module is the boundary between the app and system package managers, such as `winget` on Windows.

10. **External toolchain dependencies**
    - The application itself is native and has **no runtime Python dependency**, but it depends on external executables for key features:
      - `node` for local server hosting
      - `cloudflared` for tunnels
      - `git` and `gh` for repository and Pages deployment
    - Those tools are managed indirectly through the dependency layer and process manager.

11. **Build and packaging path**
    - `build.cpp` is a standalone C++ build helper that detects the environment and invokes MSVC with the right flags.
    - `localcel_all_in_one.cpp` is an **amalgamated single translation unit** intended to simplify compilation and CI use.
    - The `dist/` directory contains the built Windows executable artifact.

12. **Repo-level architecture summary**
    - The cleanest diagram of this repo is a **desktop controller app** in the center, with the UI at the top, core state/process management beneath it, and two outbound capability branches:
      - **Cloudflare tunnel sharing**
      - **GitHub/Git deployment**
    - A separate dependency-provisioning layer supports both branches by ensuring the required CLI tools exist on the machine.

Main entry points: [`localcel_all_in_one.cpp`](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/localcel_all_in_one.cpp) (All-in-one), [`src/deps/DependencyManager.hpp`](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DependencyManager.hpp) (Dependency API), [`src/core/ProcessManager.cpp`](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/core/ProcessManager.cpp) (Process Manager), [`src/ui/WindowsUI.cpp`](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/ui/WindowsUI.cpp) (Windows UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_src_main_cpp(("main<br/>entrypoint<br/>[main.cpp]"))
  node_src_ui_windowsui["Windows UI<br/>win32-ui<br/>[WindowsUI.cpp]"]
end

subgraph group_core["Core"]
  node_src_core_appmanager[("App Manager<br/>workspace-core<br/>[AppManager.cpp]")]
  node_src_core_processmanager["Process Manager<br/>process-orchestrator<br/>[ProcessManager.cpp]"]
  node_src_core_utils["Utils<br/>shared-helpers<br/>[Utils.cpp]"]
end

subgraph group_network["Sharing"]
  node_src_network_cloudflaremanager["Cloudflare<br/>tunnel-manager"]
end

subgraph group_deploy["Deployment"]
  node_src_deploy_gitmanager["Git Manager<br/>publish-orchestrator<br/>[GitManager.cpp]"]
end

subgraph group_deps["Dependencies"]
  node_src_deps_dependencymanager_hpp["Dependency API<br/>dependency-abstraction"]
  node_src_deps_depmgr_windows["Windows deps<br/>platform-impl<br/>[DepMgr_Windows.cpp]"]
  node_src_deps_depmgr_linux["Linux deps<br/>platform-impl<br/>[DepMgr_Linux.cpp]"]
  node_src_deps_depmgr_macos["macOS deps<br/>platform-impl<br/>[DepMgr_macOS.cpp]"]
  node_src_deps_depmgr_android["Android deps<br/>platform-impl<br/>[DepMgr_Android.cpp]"]
end

subgraph group_build["Build"]
  node_build_cpp["build.cpp<br/>build-helper<br/>[build.cpp]"]
  node_localcel_all_in_one_cpp["All-in-one<br/>amalgamation"]
  node_dist_localcel_exe["Executable<br/>artifact<br/>[Localcel.exe]"]
end

node_src_main_cpp -->|"starts"| node_src_ui_windowsui
node_src_ui_windowsui -->|"loads workspace"| node_src_core_appmanager
node_src_ui_windowsui -->|"controls processes"| node_src_core_processmanager
node_src_core_appmanager -->|"uses"| node_src_core_utils
node_src_core_appmanager -->|"coordinates"| node_src_core_processmanager
node_src_core_processmanager -->|"starts tunnel"| node_src_network_cloudflaremanager
node_src_core_processmanager -->|"publishes"| node_src_deploy_gitmanager
node_src_network_cloudflaremanager -->|"requires tools"| node_src_deps_dependencymanager_hpp
node_src_deploy_gitmanager -->|"requires tools"| node_src_deps_dependencymanager_hpp
node_src_deps_dependencymanager_hpp -->|"selects"| node_src_deps_depmgr_windows
node_src_deps_dependencymanager_hpp -->|"selects"| node_src_deps_depmgr_linux
node_src_deps_dependencymanager_hpp -->|"selects"| node_src_deps_depmgr_macos
node_src_deps_dependencymanager_hpp -->|"selects"| node_src_deps_depmgr_android
node_build_cpp -->|"builds"| node_localcel_all_in_one_cpp
node_localcel_all_in_one_cpp -->|"includes"| node_src_main_cpp
node_localcel_all_in_one_cpp -->|"includes"| node_src_ui_windowsui
node_localcel_all_in_one_cpp -->|"includes"| node_src_core_appmanager
node_localcel_all_in_one_cpp -->|"includes"| node_src_core_processmanager
node_localcel_all_in_one_cpp -->|"includes"| node_src_network_cloudflaremanager
node_localcel_all_in_one_cpp -->|"includes"| node_src_deploy_gitmanager
node_build_cpp -->|"outputs"| node_dist_localcel_exe

click node_src_main_cpp "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/main.cpp"
click node_src_ui_windowsui "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/ui/WindowsUI.cpp"
click node_src_core_appmanager "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/core/AppManager.cpp"
click node_src_core_processmanager "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/core/ProcessManager.cpp"
click node_src_core_utils "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/core/Utils.cpp"
click node_src_network_cloudflaremanager "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/network/CloudflareManager.cpp"
click node_src_deploy_gitmanager "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deploy/GitManager.cpp"
click node_src_deps_dependencymanager_hpp "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DependencyManager.hpp"
click node_src_deps_depmgr_windows "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DepMgr_Windows.cpp"
click node_src_deps_depmgr_linux "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DepMgr_Linux.cpp"
click node_src_deps_depmgr_macos "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DepMgr_macOS.cpp"
click node_src_deps_depmgr_android "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DepMgr_Android.cpp"
click node_build_cpp "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/build.cpp"
click node_localcel_all_in_one_cpp "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/localcel_all_in_one.cpp"
click node_dist_localcel_exe "https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/dist/Localcel.exe"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_main_cpp,node_src_ui_windowsui toneBlue
class node_src_core_appmanager,node_src_core_processmanager,node_src_core_utils toneAmber
class node_src_network_cloudflaremanager toneMint
class node_src_deploy_gitmanager toneRose
class node_src_deps_dependencymanager_hpp,node_src_deps_depmgr_windows,node_src_deps_depmgr_linux,node_src_deps_depmgr_macos,node_src_deps_depmgr_android toneIndigo
class node_build_cpp,node_localcel_all_in_one_cpp,node_dist_localcel_exe toneTeal
```

## Components

### Presentation

Win32 desktop UI boundary

- [main](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/main.cpp): entrypoint · Application entry point · `src/main.cpp`
- [Windows UI](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/ui/WindowsUI.cpp): win32-ui · Desktop windowing and presentation layer · `src/ui/WindowsUI.cpp`

### Core

Workspace, process, and shared utilities

- [App Manager](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/core/AppManager.cpp): workspace-core · Workspace loading and app configuration state · `src/core/AppManager.cpp`
- [Process Manager](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/core/ProcessManager.cpp): process-orchestrator · Node and cloudflared process lifecycle control · `src/core/ProcessManager.cpp`
- [Utils](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/core/Utils.cpp): shared-helpers · UTF-8, process, and JSON helpers · `src/core/Utils.cpp`

### Sharing

Cloudflare tunnel exposure path

- [Cloudflare](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/network/CloudflareManager.cpp): tunnel-manager · Cloudflare Tunnel authentication and lifecycle · `src/network/CloudflareManager.cpp`

### Deployment

GitHub publishing path

- [Git Manager](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deploy/GitManager.cpp): publish-orchestrator · GitHub repo and Pages deployment flow · `src/deploy/GitManager.cpp`

### Dependencies

External tool provisioning and detection

- [Dependency API](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DependencyManager.hpp): dependency-abstraction · Cross-platform dependency management interface · `src/deps/DependencyManager.hpp`
- [Windows deps](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DepMgr_Windows.cpp): platform-impl · Windows provisioning and detection backend · `src/deps/DepMgr_Windows.cpp`
- [Linux deps](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DepMgr_Linux.cpp): platform-impl · Linux provisioning and detection backend · `src/deps/DepMgr_Linux.cpp`
- [macOS deps](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DepMgr_macOS.cpp): platform-impl · macOS provisioning and detection backend · `src/deps/DepMgr_macOS.cpp`
- [Android deps](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/src/deps/DepMgr_Android.cpp): platform-impl · Android provisioning and detection backend · `src/deps/DepMgr_Android.cpp`

### Build

Compilation and amalgamation support

- [build.cpp](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/build.cpp): build-helper · Standalone MSVC build driver · `build.cpp`
- [All-in-one](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/localcel_all_in_one.cpp): amalgamation · Single translation unit distribution build · `localcel_all_in_one.cpp`
- [Executable](https://github.com/edwinjosephshiju/localcel.cpp-aio/blob/master/dist/Localcel.exe): artifact · Built Windows binary output · `dist/Localcel.exe`

## Connections

- main → Windows UI: starts · Launches the desktop UI
- Windows UI → App Manager: loads workspace · Uses app state and configuration services
- Windows UI → Process Manager: controls processes · Invokes runtime lifecycle operations
- App Manager → Utils: uses · Shares parsing and OS helper routines
- App Manager → Process Manager: coordinates · Delegates process-related actions
- Process Manager → Cloudflare: starts tunnel · Manages cloudflared as part of process lifecycle
- Process Manager → Git Manager: publishes · Triggers deployment workflows when needed
- Cloudflare → Dependency API: requires tools · Depends on external CLI availability
- Git Manager → Dependency API: requires tools · Depends on git and gh provisioning
- Dependency API → Windows deps: selects · Windows backend implementation
- Dependency API → Linux deps: selects · Linux backend implementation
- Dependency API → macOS deps: selects · macOS backend implementation
- Dependency API → Android deps: selects · Android backend implementation
- build.cpp → All-in-one: builds · Produces the amalgamated translation unit
- All-in-one → main: includes · Single-file entry path for distribution builds
- All-in-one → Windows UI: includes · Pulls in presentation layer code
- All-in-one → App Manager: includes · Pulls in core workspace management
- All-in-one → Process Manager: includes · Pulls in process lifecycle control
- All-in-one → Cloudflare: includes · Pulls in tunnel management
- All-in-one → Git Manager: includes · Pulls in deployment logic
- build.cpp → Executable: outputs · Build artifact target
