AgentStudio Electron IDE Architecture

Entry Point

Active Entry Point: src/main/main.ts → dist/main/main.js (as specified in package.json)

Legacy Entry Point: src/main.ts (500+ lines, direct IPC handlers) - TO BE REMOVED

Architecture Decisions

Main Process Structure

src/main/main.ts: Application entry point, window creation, menu setup
src/main/ipc-router.ts: Centralized IPC handler registration (OpenAPI-compliant)
src/main/extension-host.ts: Extension system (placeholder implementation)
src/main/security/: CSP, validation, keychain management
src/main/auto-updater.ts: Auto-update functionality

IPC Handler Pattern

All IPC handlers are registered via initializeIpcRouter() which calls:

registerEditorHandlers() - File editing operations
registerFileSystemHandlers() - File system operations
registerTerminalHandlers() - Terminal/PTY management
registerAgentHandlers() - Agent operations
registerExtensionHandlers() - Extension commands

Service Initialization

Services are initialized in src/main/main.ts before IPC router:

Extension host initialization
IPC router registration
Auto-updater setup
Window creation

Legacy main.ts Migration Status

Status: src/main.ts contains service-specific handlers that need migration:

✅ Basic handlers (get-agents, deploy-agent) - Can be migrated to ipc-router
⚠️ Service-dependent handlers (ai-chat, semantic-search, etc.) - Require service instances
⚠️ Orchestrator handlers (spawn-agent, deploy-swarm) - Require orchestrator service
⚠️ Collaboration handlers - Require collaboration service

Action Required: Migrate service-dependent handlers to ipc-router.ts with proper service injection, then delete src/main.ts.

Build Configuration

TypeScript: Strict mode enabled (strict: true, noImplicitAny: true)
Build Tool: electron-builder (primary), electron-forge (optional, requires forge.config.js)
Renderer: Vite + React
Main Process: TypeScript compiled to CommonJS

Security

Context Isolation: Enabled
Node Integration: Disabled
Sandbox: Enabled
CSP: Implemented via src/main/security/csp.ts
Preload Script: src/preload/preload.js (secure IPC bridge)

Extension System

Status: Placeholder implementation

Extension host exists but needs full implementation
Extension loading from packages/extensions/* not yet functional
Activation events not implemented
Command registration not implemented

Future Work: Complete extension host or remove if not needed.

Code-Server Integration (Option A2)

Code-server is deployed as standalone service (no iframes):

Deployment: Kubernetes/OrbStack via Helm
Access: NodePort 30080 (OrbStack) or service URL
Integration: Web app links to code-server URL (opens in new tab)
Configuration: infrastructure/helm/values-orbstack.yaml

See infrastructure/CODE_SERVER_DEPLOYMENT.md for deployment details.

kAgent Integration

kAgent deployed in same Kubernetes cluster:

Namespace: llm-agents
Controller: Manages agent lifecycle
Engine: Executes agent tasks
Access: Via kagent CLI or Kubernetes API
Configuration: infrastructure/helm/templates/kagent.yaml

Known Issues

Duplicate main.ts: Legacy file needs handler migration and deletion
Extension Host: Placeholder implementation needs completion or removal
Hardcoded Paths: Fixed in kagent.service.ts and vite.config.ts (now use environment variables)
TypeScript Strict Mode: Enabled - may reveal type errors that need fixing

File Structure

src/
├── main/
│   ├── main.ts              # Entry point (ACTIVE)
│   ├── ipc-router.ts        # IPC handlers
│   ├── extension-host.ts    # Extension system
│   ├── auto-updater.ts      # Auto-update
│   └── security/             # Security modules
├── preload/
│   └── preload.ts           # Secure IPC bridge
├── renderer/                # React UI
├── services/                # Business logic services
└── types/                   # TypeScript types

Development Workflow

Development: npm run dev (concurrently runs Vite dev server + Electron)
Build: npm run build (TypeScript + Vite)
Package: npm run package (electron-builder)
Test: npm test (Vitest)