Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
383 lines (311 loc) · 13.5 KB

ARCHITECTURE.md

File metadata and controls

383 lines (311 loc) · 13.5 KB

AI Editor Toolkit Architecture

Overview

The AI Editor Toolkit is a comprehensive system designed to monitor, clean up, and optimize AI editor processes and system resources. The architecture is modular and follows a four-phase development approach.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AI Editor Toolkit                       │
├─────────────────────────────────────────────────────────────┤
│  Phase 4: Advanced Features                               │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │ Performance     │  │ Project         │                 │
│  │ Analytics       │  │ Optimization    │                 │
│  └─────────────────┘  └─────────────────┘                 │
├─────────────────────────────────────────────────────────────┤
│  Phase 3: Editor Extension                                │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │ VS Code         │  │ Cursor          │                 │
│  │ Extension       │  │ Integration     │                 │
│  └─────────────────┘  └─────────────────┘                 │
├─────────────────────────────────────────────────────────────┤
│  Phase 2: CLI Tool                                        │
│  ┌─────────────────┐  ┌─────────────────┐                 │
│  │ Command         │  │ Configuration   │                 │
│  │ Interface       │  │ Management      │                 │
│  └─────────────────┘  └─────────────────┘                 │
├─────────────────────────────────────────────────────────────┤
│  Phase 1: Core Engine                                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐│
│  │ Process         │  │ Port            │  │ Memory       ││
│  │ Manager         │  │ Manager         │  │ Manager      ││
│  └─────────────────┘  └─────────────────┘  └──────────────┘│
└─────────────────────────────────────────────────────────────┘

Core Components

Phase 1: Core Engine

ProcessManager

Purpose: Detect, monitor, and manage AI editor processes

Key Features:

  • Process identification using pattern matching
  • Orphaned process detection
  • Resource usage monitoring
  • Cross-platform process management

Architecture:

class ProcessManager {
  - aiEditorPatterns: RegExp[]
  - aiAssistantPatterns: RegExp[]
  
  + getAllProcesses(): Promise<ProcessInfo[]>
  + getAIEditorProcesses(): Promise<AIEditorProcess[]>
  + killProcess(pid: number): Promise<boolean>
  + cleanupOrphanedProcesses(): Promise<CleanupResult>
}

PortManager

Purpose: Monitor and manage port usage by development servers

Key Features:

  • Active port detection
  • Port conflict resolution
  • Development server port management
  • Cross-platform network monitoring

Architecture:

class PortManager {
  - commonAIEditorPorts: number[]
  
  + getAllActivePorts(): Promise<PortInfo[]>
  + isPortInUse(port: number): Promise<boolean>
  + killPortProcesses(ports: number[]): Promise<CleanupResult>
  + findFreePorts(count: number): Promise<number[]>
}

MemoryManager

Purpose: Monitor system memory and optimize usage

Key Features:

  • Real-time memory monitoring
  • Memory threshold management
  • System optimization recommendations
  • Cache cleaning

Architecture:

class MemoryManager {
  - memoryThresholds: ThresholdConfig
  
  + getSystemMemoryInfo(): Promise<MemoryInfo>
  + getMemoryOptimizationRecommendations(): Promise<string[]>
  + performMemoryCleanup(): Promise<CleanupResult>
  + startMemoryMonitoring(): Promise<() => void>
}

ConfigManager

Purpose: Manage toolkit configuration and settings

Key Features:

  • Configuration file management
  • Default settings
  • Backup and restore
  • Validation

Architecture:

class ConfigManager {
  - configPath: string
  - defaultConfig: ToolkitConfig
  
  + loadConfig(): Promise<ToolkitConfig>
  + saveConfig(config: ToolkitConfig): Promise<void>
  + updateConfig(updates: Partial<ToolkitConfig>): Promise<ToolkitConfig>
  + backupConfig(): Promise<string>
}

Phase 2: CLI Tool

Command Interface

Purpose: Provide command-line access to toolkit functionality

Commands:

  • status - Show system status
  • cleanup - Clean up processes
  • kill-port - Kill processes on specific ports
  • monitor - Start monitoring
  • optimize - System optimization
  • config - Configuration management

Architecture:

// Command structure using Commander.js
program
  .command('status')
  .option('-j, --json', 'JSON output')
  .action(async (options) => {
    // Implementation
  });

Phase 3: Editor Extension

VS Code Extension

Purpose: Integrate toolkit functionality into VS Code

Components:

  • Status bar integration
  • Command palette commands
  • Background monitoring
  • Configuration management
  • Notifications

Architecture:

export function activate(context: vscode.ExtensionContext) {
  // Extension activation
  const toolkit = new AIEditorToolkit();
  
  // Register commands
  const commands = [
    vscode.commands.registerCommand('aiToolkit.showStatus', showStatus),
    vscode.commands.registerCommand('aiToolkit.cleanup', performCleanup),
    // ... more commands
  ];
  
  // Start monitoring
  initializeMonitoring();
}

Phase 4: Advanced Features

PerformanceAnalytics

Purpose: Provide detailed analytics and reporting

Features:

  • Performance metrics collection
  • Trend analysis
  • Report generation
  • Data export

Architecture:

class PerformanceAnalytics {
  - metricsHistory: PerformanceMetrics[]
  - eventsHistory: ToolkitEvent[]
  
  + recordMetrics(metrics: PerformanceMetrics): void
  + generatePerformanceReport(): Promise<PerformanceReport>
  + analyzeProject(path: string): Promise<ProjectProfile>
  + exportAnalytics(): Promise<string>
}

Data Flow

Monitoring Flow

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ System      │───▶│ Core        │───▶│ Analytics   │
│ Processes   │    │ Engine      │    │ Engine      │
└─────────────┘    └─────────────┘    └─────────────┘
                           │
                           ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ CLI/        │◀───│ Event       │───▶│ Config      │
│ Extension   │    │ System      │    │ Manager     │
└─────────────┘    └─────────────┘    └─────────────┘

Cleanup Flow

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ User        │───▶│ CLI/        │───▶│ Process     │
│ Request     │    │ Extension   │    │ Manager     │
└─────────────┘    └─────────────┘    └─────────────┘
                                              │
                                              ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Cleanup     │◀───│ Port        │◀───│ Memory      │
│ Result      │    │ Manager     │    │ Manager     │
└─────────────┘    └─────────────┘    └─────────────┘

Technology Stack

Core Technologies

  • Language: TypeScript/JavaScript
  • Runtime: Node.js 16+
  • Package Manager: npm

Dependencies

  • Process Management: ps-list, pidusage
  • Network: tcp-port-used, find-free-port
  • CLI: commander, chalk, ora, inquirer
  • System Info: systeminformation
  • File System: fs-extra
  • Scheduling: node-cron

Development Tools

  • TypeScript Compiler: tsc
  • Linting: eslint
  • Testing: jest
  • VS Code Extension: @types/vscode

Cross-Platform Considerations

Process Management

  • Windows: Uses tasklist and taskkill
  • Unix/Linux: Uses ps and kill
  • macOS: Uses ps and kill

Port Management

  • Windows: Uses netstat -ano
  • Unix/Linux: Uses netstat -tulnp and lsof
  • macOS: Uses netstat -tulnp and lsof

File Paths

  • Config Directory:
    • Windows: %USERPROFILE%\.ai-editor-toolkit
    • Unix/Linux/macOS: ~/.ai-editor-toolkit

Security Considerations

Process Safety

  • Process Protection: Excludes system-critical processes
  • Confirmation Prompts: Asks before killing processes
  • Graceful Termination: Uses SIGTERM before SIGKILL

Permission Management

  • Elevated Privileges: Handles permission errors gracefully
  • User Consent: Requires explicit user action for destructive operations

Data Privacy

  • Local Storage: All data stored locally
  • No Telemetry: No data sent to external servers
  • Configuration Backup: Automatic backup before changes

Performance Characteristics

Resource Usage

  • Memory Footprint: < 50MB during monitoring
  • CPU Usage: < 1% during normal operation
  • Disk Usage: < 10MB for logs and configuration

Scalability

  • Process Limit: Can monitor 1000+ processes
  • History Retention: Keeps last 1000 metrics entries
  • Event Storage: Stores last 500 events

Error Handling

Error Categories

  1. System Errors: Permission denied, process not found
  2. Network Errors: Port access, network unavailable
  3. Configuration Errors: Invalid config, file not found
  4. Resource Errors: Out of memory, disk full

Error Recovery

  • Graceful Degradation: Continue operation with reduced functionality
  • Automatic Retry: Retry failed operations with backoff
  • User Notification: Clear error messages and suggested actions

Testing Strategy

Unit Tests

  • Individual component testing
  • Mock external dependencies
  • Edge case handling

Integration Tests

  • Cross-component interaction
  • End-to-end workflows
  • Platform-specific behavior

Performance Tests

  • Memory usage monitoring
  • Process cleanup efficiency
  • System impact measurement

Deployment

Package Distribution

  • npm Registry: Published as npm package
  • VS Code Marketplace: Extension distribution
  • GitHub Releases: Source code and binaries

Installation Methods

  1. Global npm install: npm install -g ai-editor-toolkit
  2. VS Code Extension: Install from marketplace
  3. From Source: Clone and build locally

Future Considerations

Planned Enhancements

  • Web dashboard for remote monitoring
  • Docker container support
  • Additional editor integrations
  • Machine learning optimization
  • Team collaboration features

Architecture Evolution

  • Microservice architecture for web version
  • Plugin system for extensibility
  • Cloud synchronization capabilities
  • Real-time collaboration features

Development Guidelines

Code Organization

src/
├── core/           # Core engine components
├── cli/            # Command-line interface
├── extension/      # VS Code extension
├── advanced/       # Advanced features
├── types/          # TypeScript definitions
└── utils/          # Utility functions

Naming Conventions

  • Classes: PascalCase (e.g., ProcessManager)
  • Methods: camelCase (e.g., getAllProcesses)
  • Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_PORT)
  • Files: camelCase (e.g., processManager.ts)

Documentation Standards

  • JSDoc: All public methods documented
  • README: Comprehensive usage guide
  • Architecture: Detailed design documentation
  • API: Type definitions and examples