Project Architecture

​

Project Overview

​

Technology Stack

• Language: TypeScript
• Runtime: Node.js 20.x
• Extension Host: VS Code Extension API (^1.84.0)
• Frontend: React (webview-ui)
• Build Tool: esbuild
• Testing: Mocha, Playwright
• Protocol Buffers: For data serialization and gRPC communication

​

Directory Structure

hai-build-codegen/
├── src/                          # Main source code
│   ├── core/                     # Core extension logic
│   │   ├── api/                  # API integrations
│   │   ├── assistant-message/    # AI message handling
│   │   ├── commands/             # VS Code commands
│   │   ├── context/              # Context management
│   │   ├── controller/           # Main controllers
│   │   ├── hooks/                # Extension hooks
│   │   ├── prompts/              # System prompts
│   │   ├── storage/              # Data persistence
│   │   ├── task/                 # HAI Tasks implementation
│   │   └── webview/              # Webview communication
│   ├── exports/                  # Public API exports
│   ├── generated/                # Generated Protocol Buffer code
│   ├── shared/                   # Shared utilities
│   └── test/                     # Test files
│       ├── e2e/                  # End-to-end tests
│       └── integration/          # Integration tests
├── webview-ui/                   # React-based UI
│   ├── src/
│   │   ├── components/           # React components
│   │   ├── services/             # Frontend services
│   │   └── __tests__/            # Frontend tests
├── proto/                        # Protocol Buffer definitions
├── cli/                          # CLI implementation
├── evals/                        # Evaluation and benchmarks
├── testing-platform/             # Testing infrastructure
├── dist/                         # Compiled extension output
└── dist-standalone/              # Standalone build output

​

Core Components

​

Extension Host (src/core)

• Manages the extension lifecycle
• Handles communication between VS Code and the AI models
• Coordinates task execution and file operations

• Integrates with various LLM providers (Anthropic, OpenAI, Google, AWS Bedrock, etc.)
• Handles authentication and API communication
• Manages rate limiting and error handling

• Code indexing and semantic search
• File identification and relevance scoring
• Embedding model integration

• HAI Tasks integration with Specif AI
• Task execution and lifecycle management
• User story and task tracking

​

Webview UI (webview-ui/)

• Settings Interface: Configure LLMs, embedding models, and preferences
• Chat Interface: Interact with the AI assistant
• HAI Tasks View: Manage and execute AI-generated tasks
• Experts Interface: Create and manage custom domain experts
• MCP Marketplace: Browse and install MCP servers

​

Protocol Buffers

• State serialization and persistence
• gRPC communication for standalone mode
• Type-safe data contracts between components

​

Data Flow

User Input (VS Code)
       ↓
  Webview UI (React)
       ↓
 Webview API (messaging)
       ↓
   Controller Layer
       ↓
    API Layer → LLM Providers
       ↓
   Context Layer → Code Index
       ↓
    Task System
       ↓
 File Operations → VS Code API

​

Key Features Architecture

​

HAI Tasks

1. Tasks are generated by Specif AI or created manually
2. Stored in the extension’s global state
3. Displayed in the dedicated HAI Tasks webview
4. Executed via the controller layer with full context

​

Experts System

1. Built-in experts (read-only): .NET, Terraform, Node.js, Go
2. Custom experts stored in .hai-experts/ folder:
   • metadata.json: Expert metadata and document links
   • prompt.md: Expert guidelines
   • docs/: Processed reference documents
3. Integrated into the system prompt during code generation

​

Code Indexing

1. Background indexing of workspace files
2. Embedding generation using configured provider
3. Vector storage for semantic search
4. Relevant file identification during task execution

​

MCP Integration

1. Model Context Protocol support for extensibility
2. Marketplace for discovering and installing MCP servers
3. OAuth handling for MCP server authentication
4. Tool integration into the AI assistant workflow

​

Testing Architecture

​

Unit Tests

• Located in src/__tests__/ and component __tests__/ folders
• Run with Mocha and Node’s test runner
• Focus on individual component logic

​

Integration Tests

• Test extension functionality within VS Code
• Use @vscode/test-electron for running tests
• Verify API integrations and file operations

​

E2E Tests

• Playwright-based tests in src/test/e2e/
• Simulate real user interactions
• Test complete workflows from UI to execution
• Mock API server for backend testing

​

Build Process

1. Protocol Buffers: Generated first via npm run protos
2. Type Checking: TypeScript compilation without emit
3. Webview Build: React app bundled separately
4. Extension Bundle: esbuild bundles the extension code
5. Packaging: VSCE packages everything into a .vsix file

​

Extension Points

​

Hooks

​

Slash Commands

​

MCP Servers

​

State Management

• Global State: VS Code’s global state for cross-workspace data
• Workspace State: Workspace-specific configuration
• Protocol Buffer State: Serialized state for standalone mode
• Indexing State: Code index and embedding metadata

​

Next Steps