How edwinjosephshiju/localcel.cpp-aio works
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 All-in-one · DependencyManager.hpp Dependency API · ProcessManager.cpp Process Manager · WindowsUI.cpp Windows UI
Components 15
Presentation
Win32 desktop UI boundary
- main · Application entry point
src/main.cpp - Windows UI · Desktop windowing and presentation layer
src/ui/WindowsUI.cpp
Core
Workspace, process, and shared utilities
- App Manager · Workspace loading and app configuration state
src/core/AppManager.cpp - Process Manager · Node and cloudflared process lifecycle control
src/core/ProcessManager.cpp - Utils · UTF-8, process, and JSON helpers
src/core/Utils.cpp
Sharing
Cloudflare tunnel exposure path
- Cloudflare · Cloudflare Tunnel authentication and lifecycle
src/network/CloudflareManager.cpp
Deployment
GitHub publishing path
- Git Manager · GitHub repo and Pages deployment flow
src/deploy/GitManager.cpp
Dependencies
External tool provisioning and detection
- Dependency API · Cross-platform dependency management interface
src/deps/DependencyManager.hpp - Windows deps · Windows provisioning and detection backend
src/deps/DepMgr_Windows.cpp - Linux deps · Linux provisioning and detection backend
src/deps/DepMgr_Linux.cpp - macOS deps · macOS provisioning and detection backend
src/deps/DepMgr_macOS.cpp - Android deps · Android provisioning and detection backend
src/deps/DepMgr_Android.cpp
Build
Compilation and amalgamation support
- build.cpp · Standalone MSVC build driver
build.cpp - All-in-one · Single translation unit distribution build
localcel_all_in_one.cpp - Executable · Built Windows binary output
dist/Localcel.exe
Connections 21
- 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