[EPIC][DESKTOP]: ContextForge Desktop (React + Electron)

[crivetimihai]

🖥️ Epic: ContextForge Desktop (React + Electron)

Goal

Build a fully-featured desktop application for Windows, Linux, and macOS using React and Electron, based on the ContextForge Desktop PoC. This provides a native-like experience with system integration, offline capabilities, and improved performance.

Why Now?

1. Native Experience: Desktop app feels faster and more integrated than browser
2. System Integration: System tray, notifications, keyboard shortcuts, file access
3. Offline Support: Work with cached data when disconnected
4. Multi-Gateway: Manage multiple ContextForge instances from one app
5. Modern Stack: React 19 + TypeScript provides better DX than HTMX for complex UIs

---

🛠️ Technology Stack

Based on contextforge-desktop PoC:

Layer	Technology
Frontend	React 19, TypeScript, Tailwind CSS
UI Components	Radix UI, shadcn/ui, Lucide Icons
Desktop	Electron 39, Electron Forge
Build	Vite 7
State	React Context + Hooks
API Client	@contextforge/client (generated SDK)

---

📖 User Stories

US-1: Cross-Platform Desktop App

As a user
I want a native desktop app for my OS
So that I can manage ContextForge without a browser

Acceptance Criteria:

• Windows installer (.exe, .msi)
• macOS app bundle (.dmg, .app)
• Linux packages (.deb, .rpm, .AppImage)
• Auto-updates supported
• Native look and feel per platform

US-2: Multi-Gateway Management

As a user managing multiple gateways
I want to connect to multiple ContextForge instances
So that I can manage dev, staging, and prod from one app

Acceptance Criteria:

• Add/remove gateway connections
• Switch between gateways quickly
• Visual indicator of current gateway
• Per-gateway authentication
• Gateway health status visible

US-3: System Tray Integration

As a user
I want the app to run in the system tray
So that I can quickly access it and receive notifications

Acceptance Criteria:

• Minimize to system tray
• Tray icon shows connection status
• Quick actions from tray menu
• Desktop notifications for alerts
• Launch on system startup (optional)

US-4: Keyboard-First Experience

As a power user
I want comprehensive keyboard shortcuts
So that I can work efficiently without mouse

Acceptance Criteria:

• Global shortcut to show/hide app
• Cmd/Ctrl+K command palette
• Navigation shortcuts (Cmd+1, Cmd+2, etc.)
• Vim-style navigation in lists
• All actions accessible via keyboard

US-5: Offline Mode

As a user with intermittent connectivity
I want to view cached data when offline
So that I can review configurations without connection

Acceptance Criteria:

• Cache entity data locally
• Clear offline indicator
• Read-only mode when offline
• Queue actions for sync when online
• Conflict resolution for offline edits

US-6: Feature Parity with Web UI

As a user
I want all Admin UI features in the desktop app
So that I don't need to switch to browser

Acceptance Criteria:

• Servers, Tools, Resources, Prompts management
• Gateways and federation management
• A2A Agents management
• Metrics and observability
• User/team management
• All CRUD operations

---

📋 Implementation Tasks

Phase 1: Project Setup

• Fork/clone contextforge-desktop PoC
• Set up monorepo structure (app + shared)
• Configure Electron Forge for multi-platform
• Set up Vite + React 19 + TypeScript
• Configure Tailwind + shadcn/ui

Phase 2: Core Infrastructure

• Integrate generated TypeScript SDK
• Implement authentication flow
• Set up React Router for navigation
• Implement state management (Context + Hooks)
• Create base layout components

Phase 3: Feature Implementation

• Implement Servers management
• Implement Tools management
• Implement Resources management
• Implement Prompts management
• Implement Gateways management
• Implement Agents management
• Implement Metrics dashboards

Phase 4: Desktop Features

• System tray integration
• Desktop notifications
• Multi-gateway connection manager
• Global keyboard shortcuts
• Auto-updater

Phase 5: Offline & Sync

• Implement local data cache
• Offline mode detection
• Action queue for offline edits
• Sync and conflict resolution

Phase 6: Build & Distribution

• Windows builds (NSIS, MSI)
• macOS builds (DMG, notarization)
• Linux builds (deb, rpm, AppImage)
• Auto-update infrastructure
• Code signing for all platforms

Phase 7: Testing & Polish

• Unit tests (Vitest)
• E2E tests (Playwright)
• Cross-platform testing
• Performance optimization
• Accessibility audit

---

⚙️ Project Structure

contextforge-desktop/
├── packages/
│   ├── app/                    # Electron main process
│   │   ├── src/
│   │   │   ├── main.ts         # Electron entry
│   │   │   ├── preload.ts      # Preload scripts
│   │   │   └── ipc/            # IPC handlers
│   │   └── package.json
│   │
│   ├── renderer/               # React frontend
│   │   ├── src/
│   │   │   ├── App.tsx
│   │   │   ├── components/     # shadcn/ui components
│   │   │   ├── pages/          # Route pages
│   │   │   ├── hooks/          # Custom hooks
│   │   │   ├── contexts/       # React contexts
│   │   │   └── lib/            # Utilities
│   │   └── package.json
│   │
│   └── shared/                 # Shared types/utils
│       └── package.json
│
├── contextforge-client-ts/     # Generated SDK (git submodule or copy)
├── electron.vite.config.ts
├── forge.config.ts
└── package.json

---

🎯 Platform Requirements

Platform	Minimum Version	Architecture
Windows	Windows 10	x64, arm64
macOS	macOS 11 (Big Sur)	x64, arm64 (Apple Silicon)
Linux	Ubuntu 20.04+	x64, arm64

---

✅ Success Criteria

• App builds for Windows, macOS, Linux
• Feature parity with web Admin UI
• Multi-gateway support works
• System tray integration functional
• Auto-updates working
• Offline mode functional
• Performance acceptable (<100ms interactions)
• Code signed for all platforms

---

🔗 Dependencies

• [EPIC][SDK]: TypeScript SDK auto-generation (@hey-api/openapi-ts) #2288 - TypeScript SDK Generation (prerequisite)
• contextforge-desktop PoC

---

📚 References

• Electron Forge
• Vite + Electron
• shadcn/ui
• Radix UI
• React 19

[a-effort]

@crivetimihai , excited to see this in the queue! How can we change the label to Should ?