{

"projectName": "Qontinui Runner",

"description": "A Tauri desktop application for visual GUI automation. React 19/TypeScript frontend communicates via Tauri IPC with a Rust backend that orchestrates Python-based automation, AI sessions, and an MCP-compatible HTTP API (port 9876). Uses tab-based navigation (not React Router), a deep React context provider tree for state management, and an event-driven architecture for real-time workflow monitoring. The backend manages SQLite storage (schema v99), multi-phase workflow execution (verification-agentic loop), 200+ IPC commands, and a 60+ module MCP API server.",

"techStack": [

{

"name": "React",

"category": "frontend",

"version": "19.1.1",

"purpose": "UI component framework"

},

{

"name": "TypeScript",

"category": "frontend",

"version": "5.9.2",

"purpose": "Static type checking (strict mode enabled)"

},

{

"name": "Vite",

"category": "build",

"version": "7.1.5",

"purpose": "Build tool and dev server (port 1420)"

},

{

"name": "Tailwind CSS",

"category": "styling",

"version": "3.4.0",

"purpose": "Utility-first CSS framework with custom design tokens"

},

{

"name": "Tauri",

"category": "frontend",

"version": "2.5",

"purpose": "Desktop app framework (Rust backend + WebView frontend)"

},

{

"name": "Rust",

"category": "backend",

"version": "2021 edition",

"purpose": "Backend language for IPC commands, HTTP API, workflow execution"

},

{

"name": "Tokio",

"category": "backend",

"version": "1.x",

"purpose": "Async runtime (full features)"

},

{

"name": "Axum",

"category": "backend",

"version": "0.7",

"purpose": "HTTP API framework with WebSocket support (port 9876)"

},

{

"name": "SQLite (rusqlite)",

"category": "database",

"version": "0.31",

"purpose": "Embedded database with r2d2 connection pooling (schema v99)"

},

{

"name": "@tanstack/react-query",

"category": "state",

"version": "5.90.16",

"purpose": "Server state management (1-min stale, 1 retry)"

},

{

"name": "Radix UI",

"category": "frontend",

"version": "1.x-2.x",

"purpose": "Unstyled accessible UI primitives (dialog, dropdown, select, switch, tabs, scroll-area)"

},

{

"name": "@xyflow/react",

"category": "frontend",

"version": "12.10.0",

"purpose": "Flow diagram library for workflow builder and state machine visualization"

},

{

"name": "Monaco Editor",

"category": "frontend",

"version": "4.7.0",

"purpose": "VS Code-based code editor component"

},

{

"name": "@xterm/xterm",

"category": "frontend",

"version": "5.5.0",

"purpose": "Terminal emulator (with fit, search, web-links, canvas, webgl addons)"

},

{

"name": "Recharts",

"category": "frontend",

"version": "3.6.0",

"purpose": "Charting library for dashboards and analytics"

},

{

"name": "react-window",

"category": "frontend",

"version": "1.8.11",

"purpose": "Virtualized list/grid rendering for large datasets"

},

{

"name": "Lucide React",

"category": "frontend",

"version": "0.562.0",

"purpose": "Icon library"

},

{

"name": "react-markdown",

"category": "frontend",

"version": "10.1.0",

"purpose": "Markdown rendering with GFM and raw HTML support"

},

{

"name": "prism-react-renderer",

"category": "frontend",

"version": "2.4.1",

"purpose": "Syntax highlighting for code blocks"

},

{

"name": "dagre",

"category": "frontend",

"version": "0.8.5",

"purpose": "Directed graph layout algorithm for state machine and architecture views"

},

{

"name": "portable-pty",

"category": "backend",

"version": "0.8",

"purpose": "Cross-platform pseudo-terminal for embedded shell sessions"

},

{

"name": "tree-sitter",

"category": "backend",

"version": "0.24",

"purpose": "Parser generator for code analysis (Python, TypeScript, Rust grammars)"

},

{

"name": "reqwest",

"category": "backend",

"version": "0.12",

"purpose": "HTTP client for external API calls and AI provider communication"

},

{

"name": "rmcp",

"category": "backend",

"version": "0.1",

"purpose": "Model Context Protocol client implementation"

},

{

"name": "sentry",

"category": "backend",

"version": "0.35",

"purpose": "Error monitoring and reporting service"

},

{

"name": "tracing",

"category": "backend",

"version": "0.1",

"purpose": "Structured logging framework with file appenders"

},

{

"name": "aes-gcm",

"category": "backend",

"version": "0.10",

"purpose": "AES-256-GCM encryption for secure credential storage"

},

{

"name": "keyring",

"category": "backend",

"version": "3.6",

"purpose": "OS keyring integration for API key storage"

},

{

"name": "xcap",

"category": "backend",

"version": "0.4",

"purpose": "Screenshot capture for image recognition workflows"

},

{

"name": "cron",

"category": "backend",

"version": "0.12",

"purpose": "Cron expression parsing for scheduled task execution"

},

{

"name": "notify",

"category": "backend",

"version": "6.1",

"purpose": "File system event watching for log monitoring"

},

{

"name": "@qontinui/shared-types",

"category": "other",

"version": "workspace",

"purpose": "Unified TypeScript type definitions (single source of truth)"

},

{

"name": "@qontinui/workflow-ui",

"category": "frontend",

"version": "workspace",

"purpose": "Shared workflow builder UI components (headless + concrete)"

},

{

"name": "@qontinui/workflow-utils",

"category": "other",

"version": "workspace",

"purpose": "Pure utility functions for workflows (settings config, step metadata, formatting)"

},

{

"name": "ui-bridge",

"category": "frontend",

"version": "workspace",

"purpose": "UI Bridge SDK for AI-driven UI automation and element discovery"

},

{

"name": "qontinui-navigation",

"category": "frontend",

"version": "workspace",

"purpose": "Shared navigation structure and state management"

},

{

"name": "@qontinui/design-tokens",

"category": "styling",

"version": "1.0.0",

"purpose": "Shared design tokens for consistent theming"

},

{

"name": "Playwright",

"category": "testing",

"version": "1.57.0",

"purpose": "E2E testing framework and browser automation"

},

{

"name": "Vitest",

"category": "testing",

"version": "4.0.17",

"purpose": "Unit test framework with V8 coverage"

},

{

"name": "Storybook",

"category": "testing",

"version": "8.5.3",

"purpose": "Component documentation and visual testing"

},

{

"name": "ESLint",

"category": "build",

"version": "9.36.0",

"purpose": "JavaScript/TypeScript linter"

},

{

"name": "Prettier",

"category": "build",

"version": "3.6.2",

"purpose": "Code formatter"

}

],

"features": [

{

"id": "workflow-execution",

"name": "Unified Workflow Execution Engine",

"description": "Core 4-phase execution engine: setup ->verification ->agentic ->completion. The verification-agentic loop repeats until verification passes or max iterations reached. Orchestrated by LoopController with step-specific handlers (ui_bridge, image_recognition, api_request, shell_command, check, code_extraction, etc.). Supports approval gates, conditional routing, convergence, and resume from checkpoints.",

"status": "active",

"priority": "core",

"entryPoints": [

"src-tauri/src/unified_workflow_executor/phases.rs",

"src-tauri/src/unified_workflow_executor/loop_controller.rs",

"src-tauri/src/step_executor/"

],

"techUsed": ["Rust", "Tokio", "SQLite (rusqlite)"]

},

{

"id": "workflow-builder",

"name": "Workflow Builder",

"description": "Visual workflow editor for creating unified workflows with setup, verification, agentic, and completion phases. Uses shared @qontinui/workflow-ui components. Includes step configuration panel, library pickers (checks, prompts, shell commands, contexts, playwright tests), AI generation modal, skill import/export, and curl import. Save dialog persists to SQLite via Tauri IPC.",

"status": "active",

"priority": "core",

"entryPoints": ["src/components/workflow-builder/", "src/lib/workflow-builder/"],

"techUsed": ["React", "@qontinui/workflow-ui", "@qontinui/workflow-utils", "@xyflow/react"]

},

{

"id": "workflow-generation",

"name": "AI Workflow Generation Pipeline",

"description": "Converts natural language prompts into structured unified workflows via a multi-stage pipeline: prompt parsing ->tool discovery ->schema analysis ->step generation ->validation ->hardening ->revision. Produces phase-specific step arrays conforming to the unified workflow schema. Also generates from specs, plans, and state machines.",

"status": "active",

"priority": "core",

"entryPoints": ["src-tauri/src/workflow_generation/", "src/lib/workflow-builder/"],

"techUsed": ["Rust", "Tokio", "reqwest"]

},

{

"id": "active-dashboard",

"name": "Active Dashboard",

"description": "Real-time workflow monitoring with configurable widget grid. Assembles data from ActiveRunsContext (polls /task-runs/running every 2s), WorkflowExecutionContext (Tauri events for phase/step progress), and SharedStepDataContext (batched /current-execution/batch every 3s). Supports multi-run monitoring with run selector bar, approval dialogs, completion summaries, and auto-navigation to recap.",

"status": "active",

"priority": "core",

"entryPoints": ["src/components/active-dashboard/", "src/pages/DashboardPage.tsx"],

"techUsed": ["React", "Recharts", "react-window"]

},

{

"id": "terminal",

"name": "Terminal / Command Center",

"description": "Advanced multi-zone terminal interface backed by portable-pty. Features: zone-based grid layout (1-8 zones with preset layouts), session persistence, transcript analysis, command palette (Ctrl+Shift+K), focus history navigation, batch operations, unread tracking, workflow generation from shell sessions, and AI-powered findings extraction. Always-mounted to preserve PTY sessions across tab switches.",

"status": "active",

"priority": "core",

"entryPoints": ["src/components/terminal/TerminalPage.tsx", "src-tauri/src/terminal/"],

"techUsed": ["React", "@xterm/xterm", "portable-pty"]

},

{

"id": "run-observation",

"name": "Run Observation Suite",

"description": "Post-execution analysis across 10 sub-tabs: Run Recap (summary), Actions (execution log), Image Recognition (visual matches), Findings (AI-detected issues), State Explorer (state exploration results), Test Results (Playwright), AI Output (full conversation), AI Data (structured data viewer), Statistics (performance metrics), and Traces (execution waterfall). All wrapped in RunSelectionProvider for shared run context with RunPageLayout for consistent headers.",

"status": "active",

"priority": "core",

"entryPoints": [

"src/components/run-recap/",

"src/components/run-logs/",

"src/components/statistics/"

],

"techUsed": ["React", "Recharts", "react-window", "react-markdown"]

},

{

"id": "error-monitor",

"name": "Error Monitor",

"description": "Centralized error tracking from multiple sources (log files, browser console). Aggregates errors with severity classification (critical/error/warning/info/debug) and status workflow (new ->acknowledged ->in_progress ->resolved/ignored). Supports AI-powered fix generation, search/filter by severity/status/source/time, and browser console error integration.",

"status": "active",

"priority": "important",

"entryPoints": [

"src/components/error-monitor/ErrorMonitorTab.tsx",

"src-tauri/src/error_monitor/"

],

"techUsed": ["React", "Rust", "notify"]

},

{

"id": "process-manager",

"name": "Process Manager",

"description": "Monitor and control background processes (dev servers, databases, etc.). Features real-time status dashboard with PID/uptime/health checks, process configuration CRUD, stdout/stderr streaming, AI-powered error analysis and fix suggestions, project auto-discovery from process configs, and lifecycle management with auto-start options.",

"status": "active",

"priority": "important",

"entryPoints": [

"src/components/process-manager/ProcessManagerTab.tsx",

"src-tauri/src/process_capture/"

],

"techUsed": ["React", "Rust", "Tokio"]

},

{

"id": "ui-bridge-integration",

"name": "UI Bridge SDK Integration",

"description": "Complete SDK onboarding workflow for external apps. Four panels: Discovery (scan for running UI Bridge apps), Source Integration (install SDK, preview changes), Hook Generation (AI-powered generation of semantic hooks — 8 categories), and State Explorer (browse registered states/transitions/elements). Also generates architecture specs describing tech stack, features, and constraints.",

"status": "active",

"priority": "important",

"entryPoints": [

"src/pages/ui-bridge-integration/",

"src/lib/ui-bridge/",

"src/lib/hook-gen-prompt-builder.ts"

],

"techUsed": ["React", "ui-bridge", "Monaco Editor"]

},

{

"id": "state-machine-builder",

"name": "UI Bridge State Machine Builder",

"description": "Build state machines from SDK-enabled applications. Uses fingerprint-based discovery to identify distinct UI states. Features: app connection and state exploration (automated or manual), drag-and-drop graph editor with XYFlow, state/transition management tables, pathfinding between states, and configuration export for workflow automation.",

"status": "active",

"priority": "important",

"entryPoints": [

"src/pages/state-machine/UIBridgeStateMachinePage.tsx",

"src-tauri/src/state_machine_configs/"

],

"techUsed": ["React", "@xyflow/react", "dagre", "ui-bridge"]

},

{

"id": "specs-manager",

"name": "Specs Manager",

"description": "Central hub for creating, viewing, and managing specifications. Three-panel layout: spec tree (left), detail (center), AI chat (right). Supports multiple spec kinds: page-spec (UI assertions), architecture (tech stack/patterns), API (endpoints/models), data (schemas), dependency (module relationships), constraint (performance budgets). AI-assisted spec creation, spec-to-workflow generation, and regression checking against known issues.",

"status": "active",

"priority": "important",

"entryPoints": [

"src/pages/specs/SpecsPage.tsx",

"src/lib/spec-prompt-builder.ts",

"src/lib/spec-registry.ts"

],

"techUsed": ["React", "Monaco Editor", "react-markdown"]

},

{

"id": "generator-eval",

"name": "Generator Evaluation",

"description": "Development tool for assessing workflow generation quality. Tabs: Dashboard (success rate, duration, iterations), Pipeline Inspector (generation artifact timing), Edit Analysis (edited field heatmap, user ratings), Benchmarks (test against expected structures), Example Library (categorized quality examples), Insights (prompt confidence scores), Training Data (export for fine-tuning).",

"status": "active",

"priority": "nice-to-have",

"entryPoints": ["src/pages/GeneratorEvalPage.tsx", "src/pages/generator-eval/"],

"techUsed": ["React", "Recharts"]

},

{

"id": "reflection-dashboard",

"name": "Reflection Dashboard",

"description": "Track effectiveness of AI-driven reflection fixes across workflows. Shows effectiveness report (effective/ineffective/regression/inconclusive), recent reflection runs timeline, fix type analysis (10 categories: knowledge base, workflow, selector, tool config, context, etc.), trends over time, and filterable fix list with expandable details.",

"status": "active",

"priority": "important",

"entryPoints": ["src/components/reflection-dashboard/ReflectionDashboard.tsx"],

"techUsed": ["React", "Recharts"]

},

{

"id": "library",

"name": "Unified Asset Library",

"description": "Browse and manage saved automation assets: workflows, checks, check groups, shell commands, tasks, contexts, and playwright tests. Step Builders sub-pages provide CRUD for each asset type. Library dashboard shows unified view with search, filtering, and categorization.",

"status": "active",

"priority": "core",

"entryPoints": ["src/components/library/"],

"techUsed": ["React", "react-window"]

},

{

"id": "capture",

"name": "Interaction Capture",

"description": "Record user interactions (mouse clicks, keyboard input) and screen video for state machine creation. Features named sessions with duration/event tracking, configurable FPS, output directory settings, and event export. Feeds into the state machine discovery workflow.",

"status": "active",

"priority": "nice-to-have",

"entryPoints": ["src/components/CaptureTab.tsx", "src-tauri/src/recording/"],

"techUsed": ["React", "Rust", "xcap"]

},

{

"id": "scheduler",

"name": "Scheduled Tasks",

"description": "Schedule workflows for automated execution with cron expressions. Features task creation/editing, task list with next run times, timezone configuration, retry logic, execution history, and success rate statistics.",

"status": "active",

"priority": "nice-to-have",

"entryPoints": ["src/components/scheduler/", "src-tauri/src/scheduler/"],

"techUsed": ["React", "Rust", "cron"]

},

{

"id": "triggers",

"name": "Event Triggers",

"description": "Event-based workflow automation. Define trigger conditions (file changes, API events, schedules) mapped to target workflows. Features trigger editor, trigger inventory list, execution audit log, and filtering by event type/workflow/status.",

"status": "active",

"priority": "nice-to-have",

"entryPoints": ["src/components/triggers/", "src-tauri/src/trigger_system/"],

"techUsed": ["React", "Rust", "notify"]

},

{

"id": "mcp-api",

"name": "MCP HTTP API Server",

"description": "Axum HTTP server on port 9876 exposing 60+ API module groups: task runs, workflows, UI Bridge control, step execution, log monitoring, WebSocket streaming, shell commands, checks, contexts, prompts, findings, error monitor, RAG search, scheduler, triggers, processes, and more. Consumed by the frontend for data outside Tauri IPC, and by external MCP clients (Claude Code) for automation.",

"status": "active",

"priority": "core",

"entryPoints": ["src-tauri/src/mcp/server.rs", "src-tauri/src/mcp/mod.rs"],

"techUsed": ["Rust", "Axum", "Tokio", "tower-http"]

},

{

"id": "ai-session",

"name": "AI Session Management",

"description": "Multi-turn AI conversations with Claude and Gemini providers. Standalone useAiSession() hook decouples AI interactions from main workflow execution — used by ProcessManager, HookGeneration, SpecChat, and more. Backend manages unified AI sessions with streaming, token tracking, and cost estimation. Supports tool use, memory compression, and model overrides per workflow phase.",

"status": "active",

"priority": "core",

"entryPoints": [

"src/hooks/useAiSession.ts",

"src-tauri/src/unified_ai_session/",

"src-tauri/src/ai_provider/"

],

"techUsed": ["React", "Rust", "reqwest"]

},

{

"id": "architecture-view",

"name": "Architecture View",

"description": "Visualizes system component dependency graph derived from reflection workflow data. Two modes: Reflection (graph from execution data with stat cards, trends, component details) and SDK Projects (architecture from UI Bridge specs). Interactive node graph with dagre layout.",

"status": "active",

"priority": "nice-to-have",

"entryPoints": ["src/components/architecture-view/"],

"techUsed": ["React", "@xyflow/react", "dagre", "Recharts"]

},

{

"id": "settings",

"name": "Application Settings",

"description": "16 settings sub-tabs: Account, AI Providers, Advanced AI, Self-Healing, Playwright, Mobile, Cloud Relay, MCP Servers, Log Sources, Execution Variables, General, Storage, Backup, Updates, Instances, Debug. Each sub-tab maps from a MainTabId suffix. Persisted via Tauri IPC to SQLite settings table.",

"status": "active",

"priority": "core",

"entryPoints": ["src/components/settings/"],

"techUsed": ["React", "Radix UI"]

},

{

"id": "authentication",

"name": "Authentication & Setup",

"description": "Multi-stage initialization: API server readiness check ->auth verification (with dev auto-login) ->optional setup wizard ->main app render. LoginScreen for unauthenticated users, SetupWizard for first launch. AuthProvider context manages session state.",

"status": "active",

"priority": "core",

"entryPoints": [

"src/components/AuthProvider.tsx",

"src/components/setup-wizard/",

"src-tauri/src/auth/"

],

"techUsed": ["React", "Rust", "keyring", "aes-gcm"]

},

{

"id": "navigation",

"name": "Tab-Based Navigation",

"description": "Sidebar navigation managed by MainTabId state variable (not React Router). Sidebar renders groups from shared qontinui-navigation package (RUN, OBSERVE, BUILD, CONFIGURE, SCHEDULE, SYSTEM). Clicking items calls setActiveTab(), which triggers renderTabContent() switch. Tab state persisted per-instance in localStorage. Tab migration maps 30+ legacy IDs to current ones. Sidebar supports collapse (auto-collapse when terminal active), flyout panels for items with children (Runs, Settings), and keyboard navigation.",

"status": "active",

"priority": "core",

"entryPoints": ["src/App.tsx", "src/components/navigation/Sidebar.tsx"],

"techUsed": ["React", "qontinui-navigation"]

},

{

"id": "ui-bridge-hooks",

"name": "UI Bridge Hook Registration",

"description": "UIBridgeHooks component registers the app's state machine with UI Bridge: sidebar states, modal states (5 blocking modals), execution states, 6 navigation section states, 18+ per-tab states, 20+ transitions, and 90+ keyboard shortcuts across 7 scopes. RenderLogWrapper captures DOM snapshots. AutoRegisterProvider auto-discovers interactive elements in dev mode. RunnerPageContext provides semantic page context per tab.",

"status": "active",

"priority": "important",

"entryPoints": ["src/lib/ui-bridge/UIBridgeHooks.tsx", "src/lib/ui-bridge/intents.ts"],

"techUsed": ["React", "ui-bridge"]

}

],

"patterns": [

{

"id": "tab-based-navigation",

"name": "Tab-Based Navigation (No Router)",

"description": "Navigation uses a MainTabId state variable and a switch statement in renderTabContent() instead of React Router. Tab IDs are defined as a TypeScript union type. Sidebar groups from the shared qontinui-navigation package drive the UI. Tab state persists per-instance in localStorage with a migration system for legacy IDs.",

"category": "routing",

"usedBy": ["navigation", "ui-bridge-hooks"]

},

{

"id": "context-provider-tree",

"name": "Deep Context Provider Tree",

"description": "11+ React contexts nested in strict order: UIBridgeProvider ->AutoRegisterProvider ->AuthProvider ->NavigationProvider ->EventManagerProvider ->ExecutionProvider ->AutoContinueProvider ->TutorialProvider ->AppContent. Each provider depends on services from providers above it. Domain-specific hooks (useExecution, useActiveRuns, useWorkflowExecution) provide type-safe access.",

"category": "state-management",

"usedBy": ["workflow-execution", "active-dashboard", "authentication", "ui-bridge-hooks"]

},

{

"id": "event-router",

"name": "Observer-Pattern Event Router",

"description": "EventRouter implements the observer pattern: subscribers register handlers by event type (execution, ai_output, image, constraint, reporting). Tauri event payloads are dispatched to appropriate handler functions. Components subscribe to contexts updated by handlers, not to raw events. Three data channels converge: Tauri IPC events, WebSocket (ws://localhost:9876/ws), and HTTP polling.",

"category": "other",

"usedBy": ["workflow-execution", "active-dashboard", "run-observation"]

},

{

"id": "hmr-survival",

"name": "HMR State Survival Pattern",

"description": "Key contexts (ExecutionContext, EventManagerContext, RunSelectionContext, AuthContext) store their latest state on window.__CONTEXT_NAME__ to survive Vite Hot Module Replacement during development. On HMR, new provider instances read stashed state from window, avoiding full re-initialization. Preserves running workflows and connections across code edits.",

"category": "state-management",

"usedBy": ["workflow-execution", "active-dashboard", "authentication"]

},

{

"id": "instance-storage",

"name": "Instance-Namespaced Storage",

"description": "instanceStorage wraps localStorage with port-based namespacing. Default port 9876 stores keys as-is; other ports suffix keys with ':port' (e.g., 'qontinui-main-active-tab:9877'). Enables multiple concurrent runner instances with isolated tab state, sidebar collapse state, and per-instance settings.",

"category": "state-management",

"usedBy": ["navigation", "settings", "active-dashboard"]

},

{

"id": "shared-packages",

"name": "Monorepo Shared Packages",

"description": "4-layer architecture: App-specific (runner/web) ->@qontinui/workflow-ui (concrete + headless components) ->@qontinui/workflow-utils (pure functions, settings config) ->@qontinui/shared-types (type definitions). Boolean toggle settings defined declaratively in WORKFLOW_SETTINGS_CONFIG render automatically in both frontends.",

"category": "other",

"usedBy": ["workflow-builder", "library", "settings"]

},

{

"id": "tauri-ipc-bridge",

"name": "Tauri IPC Command Architecture",

"description": "200+ Tauri IPC commands organized across 30+ Rust modules sharing a common AppState struct. AppState contains BridgeManager, ExtractionExecutor, CheckpointDb, McpClientManager, ErrorMonitorHandle, SdkConnectionManager, UrlLockManager, ProcessCaptureManager, and atomic flags. Commands are registered in main.rs and invoked from the frontend via @tauri-apps/api.",

"category": "api",

"usedBy": ["workflow-execution", "terminal", "settings", "authentication", "mcp-api"]

},

{

"id": "verification-agentic-loop",

"name": "Verification-Agentic Loop",

"description": "Core execution pattern: (1) Run setup steps once. (2) Enter loop: run verification ->if pass, exit ->if fail, run agentic phase (AI fixes) ->increment iteration ->repeat. (3) Run completion steps only on success. LoopController tracks iteration count against max_iterations. Each iteration recorded in workflow_verification_phase_results table.",

"category": "other",

"usedBy": ["workflow-execution", "reflection-dashboard"]

},

{

"id": "always-mounted-terminal",

"name": "Always-Mounted Terminal",

"description": "The Terminal page is rendered outside the main switch statement in an absolute-positioned overlay with visibility toggled via CSS. It remains mounted at all times to preserve PTY sessions, scrollback buffers, and WebSocket connections across tab switches. All other tab content mounts/unmounts normally.",

"category": "routing",

"usedBy": ["terminal", "navigation"]

},

{

"id": "ai-session-hook",

"name": "Standalone AI Session Hook",

"description": "useAiSession() hook provides component-level AI interactions decoupled from main workflow execution. Returns taskRunId, sessionState, messages, streamingContent, with createSession(), sendMessage(), interrupt(), close() methods. Used by ProcessManager (AI fix), HookGeneration, SpecChat, and other components that need independent AI conversations.",

"category": "state-management",

"usedBy": ["ai-session", "process-manager", "ui-bridge-integration", "specs-manager"]

},

{

"id": "run-selection-provider",

"name": "Shared Run Selection Context",

"description": "All Observe-group tabs are wrapped in RunSelectionProvider, sharing a selected task run ID. Navigating between Observe sub-pages retains run context. The selected run ID persists in instanceStorage so recap pages automatically load the correct run after completion.",

"category": "state-management",

"usedBy": ["run-observation", "active-dashboard"]

},

{

"id": "shared-step-data-batching",

"name": "Batched Step Data Polling",

"description": "SharedStepDataContext fetches step execution data via a single batched API call (GET /current-execution/batch) rather than per-widget calls. Polls every 3 seconds, also updates on Tauri 'step-progress' events (debounced 200ms). All dashboard widgets consume from this shared context, eliminating duplicate API calls.",

"category": "api",

"usedBy": ["active-dashboard"]

},

{

"id": "python-bridge-manager",

"name": "Python Bridge Process Manager",

"description": "BridgeManager manages Python subprocess bridges for workflow execution. Two modes: exclusive (GUI automation — one workflow, holds display lock) and headless (parallel workflows allowed). Each bridge spawns a Python subprocess communicating via JSON over stdin/stdout with heartbeat monitoring and cleanup.",

"category": "other",

"usedBy": ["workflow-execution"]

}

],

"dependencies": [

{

"featureId": "workflow-execution",

"dependsOn": "mcp-api",

"type": "uses",

"description": "Workflow state and live output accessible via HTTP API endpoints"

},

{

"featureId": "workflow-execution",

"dependsOn": "ai-session",

"type": "requires",

"description": "Agentic phase creates AI sessions for fix generation"

},

{

"featureId": "workflow-builder",

"dependsOn": "library",

"type": "uses",

"description": "Builder uses library pickers to select checks, prompts, shell commands, contexts"

},

{

"featureId": "workflow-builder",

"dependsOn": "workflow-generation",

"type": "uses",

"description": "AI Generate modal triggers workflow generation pipeline"

},

{

"featureId": "active-dashboard",

"dependsOn": "workflow-execution",

"type": "requires",

"description": "Dashboard monitors live execution state via contexts and events"

},

{

"featureId": "active-dashboard",

"dependsOn": "mcp-api",

"type": "uses",

"description": "Polls /task-runs/running and /current-execution/batch for live data"

},

{

"featureId": "run-observation",

"dependsOn": "workflow-execution",

"type": "requires",

"description": "Observe tabs display results from completed workflow executions"

},

{

"featureId": "terminal",

"dependsOn": "workflow-generation",

"type": "uses",

"description": "Terminal sessions can generate workflows from shell command output"

},

{

"featureId": "terminal",

"dependsOn": "ai-session",

"type": "uses",

"description": "Terminal analysis panels use AI sessions for findings extraction"

},

{

"featureId": "error-monitor",

"dependsOn": "ai-session",

"type": "uses",

"description": "AI-powered fix generation for detected errors"

},

{

"featureId": "process-manager",

"dependsOn": "ai-session",

"type": "uses",

"description": "AI fix suggestions for process errors via useAiSession hook"

},

{

"featureId": "ui-bridge-integration",

"dependsOn": "ai-session",

"type": "uses",

"description": "Hook generation uses AI sessions for code generation"

},

{

"featureId": "ui-bridge-integration",

"dependsOn": "specs-manager",

"type": "uses",

"description": "Architecture spec generation feeds into specs system"

},

{

"featureId": "state-machine-builder",

"dependsOn": "ui-bridge-integration",

"type": "requires",

"description": "Discovers states from SDK-enabled apps via UI Bridge connection"

},

{

"featureId": "state-machine-builder",

"dependsOn": "workflow-generation",

"type": "uses",

"description": "Generates workflows from state machine configurations"

},

{

"featureId": "specs-manager",

"dependsOn": "workflow-generation",

"type": "uses",

"description": "Spec-to-workflow pipeline generates verification workflows from specs"

},

{

"featureId": "specs-manager",

"dependsOn": "ai-session",

"type": "uses",

"description": "AI chat panel for spec creation and modification"

},

{

"featureId": "reflection-dashboard",

"dependsOn": "workflow-execution",

"type": "requires",

"description": "Analyzes fix effectiveness from reflection workflow execution data"

},

{

"featureId": "reflection-dashboard",

"dependsOn": "architecture-view",

"type": "uses",

"description": "Reflection data feeds into the architecture dependency graph"

},

{

"featureId": "architecture-view",

"dependsOn": "specs-manager",

"type": "uses",

"description": "SDK Projects mode displays architecture from UI Bridge specs"

},

{

"featureId": "generator-eval",

"dependsOn": "workflow-generation",

"type": "requires",

"description": "Evaluates quality of the workflow generation pipeline"

},

{

"featureId": "scheduler",

"dependsOn": "workflow-execution",

"type": "requires",

"description": "Scheduled tasks trigger workflow execution at configured times"

},

{

"featureId": "triggers",

"dependsOn": "workflow-execution",

"type": "requires",

"description": "Triggers start workflow execution based on event conditions"

},

{

"featureId": "capture",

"dependsOn": "state-machine-builder",

"type": "uses",

"description": "Captured interactions feed into state machine discovery workflow"

},

{

"featureId": "ui-bridge-hooks",

"dependsOn": "navigation",

"type": "requires",

"description": "Hooks register states and transitions based on active tab and navigation state"

},

{

"featureId": "navigation",

"dependsOn": "authentication",

"type": "requires",

"description": "Main app navigation only renders after authentication succeeds"

},

{

"featureId": "library",

"dependsOn": "mcp-api",

"type": "uses",

"description": "Library CRUD operations use HTTP API endpoints"

}

],

"directories": [

{

"path": "src/",

"purpose": "React/TypeScript frontend source",

"required": true

},

{

"path": "src/components/",

"purpose": "React components organized by feature (40+ directories: active-dashboard, terminal, workflow-builder, error-monitor, process-manager, settings, etc.)",

"required": true

},

{

"path": "src/pages/",

"purpose": "Top-level page components (specs, generator-eval, ui-bridge-integration, state-machine, dashboard)",

"required": true

},

{

"path": "src/contexts/",

"purpose": "11 React context providers (ExecutionContext, ActiveRunsContext, WorkflowExecutionContext, EventManagerContext, etc.)",

"required": true

},

{

"path": "src/hooks/",

"purpose": "70+ custom React hooks organized by domain (execution, AI, config, monitoring, real-time, etc.)",

"required": true

},

{

"path": "src/services/",

"purpose": "30+ service modules for data fetching, side effects, and business logic",

"required": true

},

{

"path": "src/managers/",

"purpose": "Business logic coordinators (EventRouter, ActionLogManager, ConfigManager, LogManager, WindowManager)",

"required": true

},

{

"path": "src/lib/",

"purpose": "Pure utilities, API clients, prompt builders, UI Bridge integration, workflow builder helpers",

"required": true

},

{

"path": "src/lib/ui-bridge/",

"purpose": "UI Bridge SDK integration: UIBridgeHooks, intents, RenderLogWrapper, RunnerPageContext",

"required": true

},

{

"path": "src/types/",

"purpose": "50+ TypeScript type definition files organized by feature",

"required": true

},

{

"path": "src-tauri/",

"purpose": "Rust backend source (Tauri framework)",

"required": true

},

{

"path": "src-tauri/src/",

"purpose": "100+ Rust modules: execution engine, AI providers, database, MCP API, process management, terminal, etc.",

"required": true

},

{

"path": "src-tauri/src/mcp/",

"purpose": "60+ MCP API modules: task_runs, workflows, ui_bridge, checks, contexts, error_monitor, terminals, etc.",

"required": true

},

{

"path": "src-tauri/src/unified_workflow_executor/",

"purpose": "13 workflow executor modules: phases, loop_controller, conditional_routing, convergence, approval, resume, etc.",

"required": true

},

{

"path": "src-tauri/src/database/",

"purpose": "SQLite schema (v99), migrations, and query modules",

"required": true

},

{

"path": "src-tauri/src/ai_provider/",

"purpose": "AI provider abstraction (Claude, Gemini) with unified session interface",

"required": true

},

{

"path": "src-tauri/src/terminal/",

"purpose": "Embedded PTY terminal backend with session management",

"required": true

},

{

"path": "src-tauri/src/process_capture/",

"purpose": "Background process lifecycle management, output capture, and health monitoring",

"required": true

}

],

"constraints": [

{

"id": "no-react-router",

"description": "The app uses tab-based navigation with a MainTabId state variable and switch statement, NOT React Router. All 'routing' is via setActiveTab() and the shared qontinui-navigation package.",

"category": "convention"

},

{

"id": "terminal-always-mounted",

"description": "The Terminal page must remain always-mounted (outside the tab switch statement) in an absolute overlay to preserve PTY sessions, scrollback buffers, and WebSocket connections across tab switches.",

"category": "convention"

},

{

"id": "provider-ordering",

"description": "The React context provider tree must follow strict nesting order (UIBridgeProvider outermost ->AppContent innermost). Each provider depends on services from providers above it — reordering would break context dependencies.",

"category": "convention"

},

{

"id": "min-viewport",

"description": "The app shell enforces a minimum viewport of 1200x700px to ensure all UI elements render correctly.",

"category": "compatibility"

},

{

"id": "python-stdout-json",

"description": "The Python bridge subprocess requires clean JSON on stdout. All Python logging is disabled (QONTINUI_DISABLE_CONSOLE_LOGGING=1) to prevent log corruption of the JSON stream parsed by the Rust backend.",

"category": "compatibility"

},

{

"id": "instance-isolation",

"description": "Multiple runner instances can run concurrently on different ports. All per-instance state must use instanceStorage (port-namespaced localStorage) rather than plain localStorage to prevent cross-instance state collisions.",

"category": "convention"

},

{

"id": "schema-migration",

"description": "SQLite schema uses incremental versioning (currently v99). Migrations are applied sequentially on startup. New fields require updating schema.sql, database/mod.rs (migration + queries), and all struct construction sites across the Rust codebase.",

"category": "convention"

},

{

"id": "no-node-kill",

"description": "Never kill node.exe or powershell.exe processes as this terminates Claude Code sessions. Use dev-start.ps1 for service restarts which has built-in protections.",

"category": "convention"

},

{

"id": "tauri-ipc-thin",

"description": "Keep the Tauri IPC bridge layer thin and focused. The runner coordinates workflows but delegates ALL GUI actions to the Python library's ActionExecutor.",

"category": "convention"

},

{

"id": "no-backward-compat",

"description": "Project is in active development. Backward compatibility is NOT a priority. Delete over deprecate, refactor aggressively, prefer breaking changes with clean code over maintaining legacy shims.",

"category": "convention"

},

{

"id": "shared-types-source-of-truth",

"description": "TypeScript types in @qontinui/shared-types (qontinui-schemas/ts/) are the single source of truth. Rebuild with npm run build after changes. Both runner and web frontends consume the same types.",

"category": "convention"

},

{

"id": "ui-bridge-page-context",

"description": "usePageContext is handled by RunnerPageContext in App.tsx (not in UIBridgeHooks). UIBridgeHooks covers route awareness, state machine, keyboard shortcuts, and annotations only — never duplicate page context.",

"category": "convention"

}

],

"agenticStructure": {

"agents": [

{

"id": "supervisor",

"name": "Supervisor",

"role": "orchestrator",

"description": "Meta-orchestrator managing runner lifecycle and multi-iteration workflow loops. Supports simple mode (repeat workflow) and pipeline mode (build ->execute ->reflect ->fix cycle). Controls runner restart, workflow rebuild, and Claude spawn for fix implementation.",

"capabilities": [

"process-management",

"workflow-loop",

"auto-debug",

"crash-recovery",

"pipeline-orchestration"

],

"delegatesTo": ["runner"],

"triggers": ["user-action", "crash-detection", "scheduled-task"],

"decisionAuthority": [

"loop-exit-strategy",

"runner-restart",

"workflow-rebuild",

"fix-implementation-spawn"

]

},

{

"id": "runner",

"name": "Runner Execution Engine",

"role": "executor",

"description": "Core workflow execution engine. Receives workflow definitions and executes them through the unified 4-phase loop. Manages AI sessions, step execution, and checkpoint/resume.",

"capabilities": [

"workflow-execution",

"step-orchestration",

"checkpoint-resume",

"multi-stage"

],

"delegatesTo": ["loop-controller", "workflow-generator", "reflection-system"],

"triggers": ["api-request", "supervisor-command"],

"decisionAuthority": ["workflow-routing", "stage-selection"]

},

{

"id": "loop-controller",

"name": "Verification-Agentic Loop",

"role": "executor",

"description": "4-phase execution loop: setup ->verification ->agentic ->completion. Verification is the sole authority for loop exit — AI cannot bypass it. Repeats verification-agentic cycle until checks pass or max iterations reached.",

"parentAgent": "runner",

"capabilities": ["verification", "agentic-execution", "completion", "sweep"],

"delegatesTo": ["step-executor", "ai-session-executor"],

"triggers": ["workflow-start"],

"decisionAuthority": [

"loop-exit",

"phase-selection",

"sweep-trigger",

"unfixable-detection"

]

},

{

"id": "step-executor",

"name": "Step Executor",

"role": "executor",

"description": "Polymorphic execution engine for 24 step types including shell commands, API requests, UI Bridge interactions, Playwright tests, MCP calls, and checks. Each step type has a dedicated handler.",

"parentAgent": "loop-controller",

"capabilities": [

"shell-command",

"api-request",

"ui-bridge",

"playwright",

"mcp-call",

"check",

"screenshot"

],

"triggers": ["phase-execution"],

"decisionAuthority": ["step-retry", "error-classification"]

},

{

"id": "ai-session-executor",

"name": "AI Session Executor",

"role": "session",

"description": "Manages interactive Claude CLI sessions for the agentic phase. Builds context from verification failures, previous iterations, and project knowledge. Parses AI output for reflection fixes and injected steps.",

"parentAgent": "loop-controller",

"capabilities": [

"context-building",

"claude-cli-management",