Architecture

Orbit follows a strict separation between the filesystem and the UI. Filesystem access never leaves the main process, and the renderer talks to it through a single, narrow bridge.

main process (Node)              preload                renderer (React)
───────────────────────         ───────                ────────────────
scanner    ──┐
settings   ──┼─► ipcMain.handle ──► contextBridge ──► window.api.invoke(...)
launcher   ──┘   (settings.json)    (window.api)          │
                                                            ▼
                                                  OrbitProvider ──► views

1. Scan — main process

src/main/scanner walks your projects directory, parses each package.json, matches dependencies against the technology registry, and detects workspace roots. Member packages are grouped under their closest workspace; everything else is returned as a standalone project. Filesystem access never leaves the main process.

2. Settings & launch — main process

src/main/settings persists a small JSON document (projects directory and launcher preferences) in the app's user-data folder and resolves it on demand. src/main/launcher holds the editor and terminal presets and detects which ones are installed; opening a project re-resolves the command at launch time and spawns it with shell: false.

3. Bridge — preload

A single, narrow window.api.invoke(channel, ...args) method is exposed through contextBridge with contextIsolation enabled. There is no nodeIntegration in the renderer, and unrestricted IPC is never exposed.

4. State — renderer

OrbitProvider loads the snapshot once on mount, derives technology statistics and the combined project list (standalone plus workspace members), and drives every view. Rescans keep the last good results on screen if something goes wrong.

5. Views

Overview, All Projects, Workspaces, Technologies, Favorites, and Settings render from that single source of truth.

Project structure

├─ main/               # Electron main process
│  ├─ scanner/         # Scanning, tech detection, and project actions
│  ├─ settings/        # JSON settings store (projects root, launchers)
│  ├─ launcher/        # Editor/terminal catalogue and detection
│  ├─ ipc/             # Typed IPC handler registration
│  └─ window/          # BrowserWindow creation
├─ preload/            # contextBridge — exposes the narrow window.api
├─ renderer/           # React application
│  └─ src/
│     ├─ app/          # Entry point and global styles
│     ├─ components/   # Views and UI primitives
│     ├─ contexts/     # Context definitions
│     ├─ providers/    # State providers (Orbit data, toasts)
│     ├─ hooks/        # Reusable hooks (search hotkey, favorites, etc.)
│     ├─ lib/          # Formatting, technology labels, and icon mappings
│     └─ services/     # Renderer-side adapter over the preload bridge
└─ shared/             # Types shared across main, preload, and renderer

Tech stack