Project Architecture

This project uses a frontend/backend separated + standalone local Runtime Server architecture. Web, Tauri, and Electron share the same frontend, while host-specific responsibilities stay in the host layer and core logic stays in the runtime.

Architecture Layers

Frontend

The frontend uses React + Vite + TypeScript. It is responsible for rendering, interaction flow, and state presentation, but does not directly access the filesystem, database, or system APIs. The shared frontend maintains a server state model that distinguishes local server, default server, and current server, and the UI can switch the server IP and port directly.

The current i18n approach follows the style of opencode/packages/app:

• typed TypeScript dictionaries
• LanguageProvider + useLanguage()
• English fallback
• locale persistence in local storage
• lazy loading for non-default locales

Runtime Contract

Frontend and backend communicate through a unified contract. The current minimal endpoints are:

• GET /api/health
• GET /api/hello

This contract layer defines shared request, response, and platform models.

Host Adapter

The host layer connects the shared frontend to the runtime and handles platform-specific integration.

• Web: CLI or environment variables provide the default server, and the frontend can switch to another server in the UI
• Electron: the main process starts the local runtime and passes the shared desktop host contract to the frontend through preload
• Tauri: the Rust host starts or resolves the local runtime and passes the shared desktop host contract to the frontend through bindings

Runtime Server

The runtime uses Node.js + TypeScript + Hono and contains the core application behavior. The frontend does not own the core state directly; it consumes runtime data and capabilities through the shared contract.

Startup Experience

Electron and Tauri now use a render-first + host-owned init startup model:

• the window and shared frontend render first
• the host resolves initialization asynchronously
• the frontend then connects using the host-provided local/default/current server state

This makes the startup flow much closer to opencode than hardcoding localhost in renderer entry files.

Desktop Runtime Distribution

Packaged desktop apps do not depend on a system-installed Node runtime.

• Electron: uses Electron's own runtime to start the embedded runtime
• Tauri: bundles a Node executable and runtime assets inside the application package

The current desktop packaging strategy is current-OS-first:

• the Electron path has been validated in the current development environment
• the Tauri runtime preparation script currently supports and validates linux x64

CLI Package Distribution

The repository now includes a minimal opencode-style distribution skeleton:

• a wrapper package: dist/npm/openpanel
• a current-platform package: dist/npm/openpanel-<platform>-<arch>
• wrapper resolution through bin/openpanel.js + postinstall.mjs
• platform runtime assets bundled from apps/runtime/dist-desktop and apps/web/dist

Build the local distribution packages with:

pnpm build:packages

Run the local install smoke test with:

pnpm smoke:packages

Publish the generated npm packages in the correct order with:

pnpm publish:packages -- --dry-run

This currently targets the current OS only and is intended as a local packaging foundation, not a full multi-platform publish pipeline yet. The generated wrapper package is designed to work together with the matching current-platform package, rather than as a standalone universal tarball.

GitLab CI Packaging

The repository now includes a .gitlab-ci.yml pipeline designed around native runners per OS:

• verify:linux runs typecheck, full build, npm package build, and smoke checks
• package:npm emits npm wrapper/platform artifacts
• package:electron:* emits Electron bundles on native Linux/macOS/Windows runners
• package:tauri:* emits Tauri bundles on native Linux/macOS/Windows runners
• release:manifest collects packaged outputs into dist/release and generates SHA256SUMS.txt
• publish:npm automatically runs on Git tags and publishes platform packages first, then the wrapper package
• release:gitlab automatically creates or updates the GitLab Release record for the tag after packaging and npm publish complete

Desktop packaging is intentionally runner-native. The pipeline does not assume fake cross-platform desktop packaging from a single host.

Tag-driven release flow:

1. create and push a Git tag
2. GitLab runs verify/package jobs
3. publish:npm publishes npm packages on the tag pipeline
4. release:gitlab creates or updates the GitLab Release entry for that tag

Expected GitLab runner tags:

• linux
• macos
• windows

The Linux jobs assume system packages required by Tauri are available or installable in CI, including libwebkit2gtk-4.1-dev, libayatana-appindicator3-dev, librsvg2-dev, patchelf, curl, and unzip.

Common Commands

# install dependencies
pnpm install

# link the openpanel command globally
npm link

# typecheck
pnpm typecheck

# build everything
pnpm build

# build local wrapper/platform install packages
pnpm build:packages

# run local install smoke test for generated packages
pnpm smoke:packages

# publish platform packages first and wrapper last
pnpm publish:packages -- --dry-run

# bump versions, create release commit, create tag, and push the tag
node ./script/bump-version.mjs 0.1.1

# collect release artifacts into dist/release
pnpm release:artifacts -- --label local --out dist/release dist/npm

# generate SHA256SUMS.txt for dist/release
pnpm release:manifest

# start Web
pnpm dev:web

# start Web through the CLI (also starts runtime)
openpanel web

# start Web with a custom runtime host and port
openpanel web --hostname 127.0.0.1 --port 8791

# start runtime only with a custom host and port
openpanel runtime --hostname 127.0.0.1 --port 8791

# start Electron
pnpm dev:electron

# start Tauri
pnpm dev:tauri

# start runtime only
pnpm dev:runtime

# run runtime tests
pnpm --filter @openpanel/runtime test

# build openpanel (Electron) only
pnpm --filter @openpanel/desktop-electron build

# package openpanel (Electron) for the current native OS
pnpm --filter @openpanel/desktop-electron package

# package openpanel (Electron) for a specific native OS runner
pnpm --filter @openpanel/desktop-electron package:linux
pnpm --filter @openpanel/desktop-electron package:mac
pnpm --filter @openpanel/desktop-electron package:win

# build openpanel (Tauri) only
pnpm --filter @openpanel/desktop-tauri build

# package openpanel (Tauri) for the current native OS
pnpm --filter @openpanel/desktop-tauri package

# package openpanel (Tauri) for a specific native OS runner
pnpm --filter @openpanel/desktop-tauri package:linux
pnpm --filter @openpanel/desktop-tauri package:mac
pnpm --filter @openpanel/desktop-tauri package:win

Directory Structure

apps/
  web/                  # Web frontend entry
  desktop-tauri/        # openpanel Tauri host
  desktop-electron/     # openpanel Electron host
  runtime/              # Node.js + TypeScript local service

packages/
  frontend/             # Shared pages and frontend logic
  frontend/src/i18n/    # Multilingual message dictionaries
  sdk/                  # Frontend runtime client wrapper
  shared/               # Shared types and constants