# 🏛️ Plugin Architecture

This guide provides a technical overview of the Acode AI CLI Assistant Plugin architecture, components, and design patterns.

## 🎯 Overview

The plugin is built using modern JavaScript with a modular architecture that integrates seamlessly with Acode's plugin system while providing advanced AI capabilities.

## 📁 Project Structure

```
Acode-Plugin-AI-cli/
├── src/
│   ├── main.js          # Main plugin entry point
│   ├── constants.js     # Configuration constants
│   ├── api_key.js      # API key encryption/management
│   ├── utils.js        # Utility functions
│   └── style.scss      # Styling
├── dist/
│   ├── main.js         # Bundled plugin code
│   └── assets/         # Plugin assets
├── docs/               # Documentation files
├── package.json        # Project dependencies and metadata
├── plugin.json         # Acode plugin configuration
└── build.mjs           # Build process configuration
```

## 🧠 Core Components

### AI Assistant Class
The main plugin class that handles:
- Initialization and setup
- UI rendering and management
- AI provider integration
- Message history handling
- File operations

### API Key Manager
Responsible for:
- Secure encryption of API keys using AES-GCM
- Passphrase-based key derivation with PBKDF2
- Storage and retrieval of encrypted keys
- Key validation and management

### Real-Time Analysis Engine
Handles:
- Code change detection
- Debounce timing management
- AI request optimization
- Error detection and suggestions

### Bulk Operations Manager
Manages:
- Multi-file operations
- Pattern-based renaming
- Directory organization
- File movement and deletion

## 🔌 AI Provider Integration

### Supported Providers
The plugin integrates with multiple AI providers through dedicated classes:

- **OpenAI**: Using `@langchain/openai` package
- **Google Gemini**: Using `@langchain/google-genai` package
- **Ollama**: Using `@langchain/community` package
- **Groq**: Using `@langchain/groq` package
- **Anthropic Claude**: Using `@langchain/anthropic` package
- **OpenRouter**: Custom OpenAI-like integration
- **Qwen**: Custom OpenAI-like integration
- **OpenAI-Like**: Generic OpenAI-compatible API integration

### Provider Abstraction
All providers implement a common interface:
```javascript
class AIProvider {
  async getResponse(prompt) { /* Implementation */ }
  async streamResponse(prompt) { /* Implementation */ }
  validateApiKey(apiKey) { /* Implementation */ }
}
```

## 🎨 UI Architecture

### Scoped Styling
All plugin styles are scoped to prevent conflicts:
```scss
#acode-ai-assistant {
  // All styles contained within this scope
}
```

### Component-Based Design
UI elements are modular:
- **Chat Interface**: Message display, input area, action buttons
- **Dialog Components**: History browser, settings panel, file selector
- **Widgets**: Real-time suggestions, error markers, performance indicators

### Responsive Framework
- CSS variables for consistent theming
- Media queries for device-specific layouts
- Flexible components that adapt to screen size

## 🔐 Security Architecture

### Encryption Layer
- **AES-GCM**: For encrypting sensitive data
- **PBKDF2**: For secure key derivation
- **Random IVs**: For unique encryption per entry

### Data Protection
- API keys never stored in plain text
- Passphrases never stored or transmitted
- Local storage isolation from other plugins

### Communication Security
- HTTPS-only API connections
- Secure header management
- Token usage monitoring

## 📦 Build System

### ESBuild Configuration
The plugin uses ESBuild for fast bundling:
```javascript
// build.mjs
import * as esbuild from "esbuild";
import { sassPlugin } from "esbuild-sass-plugin";

let result = await esbuild.build({
  entryPoints: ["src/main.js"],
  bundle: true,
  minify: true,
  outdir: "dist",
  plugins: [
    sassPlugin({
      type: "css-text",
    }),
  ],
});
```

### Asset Management
- SVG icons for crisp rendering
- SCSS for maintainable styling
- JSON configuration files

### Packaging
- Automated ZIP packaging for distribution
- Asset copying and optimization
- Version management through package.json

## 🔄 Data Flow

### User Interaction Flow
1. User triggers plugin through UI or keyboard shortcut
2. Plugin initializes and renders interface
3. User inputs query or selects code
4. Plugin processes input and sends to AI provider
5. AI response is received and formatted
6. Response is displayed with markdown rendering
7. User can interact with response (copy code, etc.)

### Real-Time Analysis Flow
1. Editor content change detected
2. Debounce timer initiated
3. Content analyzed for context
4. AI request prepared with context
5. Response cached for future use
6. UI updated with suggestions

### Bulk Operations Flow
1. User selects operation type
2. File selection interface presented
3. Operation parameters configured
4. AI analysis performed if needed
5. Changes previewed
6. User confirms operation
7. Files processed in batch

## 🧪 Testing Architecture

### Unit Testing
- Component-level testing
- API integration testing
- Security validation testing

### Integration Testing
- Acode plugin system compatibility
- Cross-provider functionality
- UI responsiveness testing

### Performance Testing
- Response time monitoring
- Memory usage tracking
- Battery impact assessment

## 📈 Monitoring and Analytics

### Built-In Metrics
- Token usage tracking
- Response time measurement
- Error rate monitoring
- Feature usage statistics

### Debugging Support
- Console logging for development
- Error boundary implementations
- Performance profiling hooks

## 🛠️ Extensibility Points

### Plugin Hooks
- Acode command registration
- Context menu integration
- Keyboard shortcut binding
- Theme adaptation

### AI Extension Points
- Provider interface for adding new AI services
- Custom prompt templates
- Response formatting customization
- Cache strategy modification

### UI Extension Points
- Custom component injection
- Theme variable overrides
- Layout modification hooks
- Animation customization

## 🐛 Troubleshooting Architecture Issues

### Common Problems

#### Build Failures
- Dependency resolution issues
- SCSS compilation errors
- Asset copying problems

#### Runtime Errors
- API provider initialization failures
- UI rendering issues
- Storage access problems

#### Integration Issues
- Acode version compatibility
- Plugin conflict resolution
- Resource limitation handling

### Architecture Verification

To verify architectural components are working:
1. Check that main.js initializes properly
2. Verify API key manager encrypts/decrypts correctly
3. Test real-time analysis engine responsiveness
4. Confirm bulk operations manager processes files

## 📞 Getting Help

If you encounter architectural issues:
1. Check the [Common Issues](Common-Issues.md) documentation
2. Visit our [GitHub Issues](https://github.com/RenzMc/Acode-Plugin-AI-cli/issues) page
3. Join our [Discussions](https://github.com/RenzMc/Acode-Plugin-AI-cli/discussions) community for support

---

<div align="center">

[🏠 Home](Home.md) | [⬆ Back to Top](#-plugin-architecture) | [🔌 API Integration](API-Integration.md)

</div>