Skip to content

Latest commit

 

History

History
142 lines (111 loc) · 4.39 KB

ARCHITECTURE.md

File metadata and controls

142 lines (111 loc) · 4.39 KB

Extension Architecture

Overview

The CSS & JS Minifier extension follows a modular architecture pattern that separates concerns into distinct layers for better maintainability, testability, and code reusability.

Architecture Layers

1. Extension Entry Point (src/extension.ts)

  • Purpose: Clean activation/deactivation lifecycle management
  • Responsibilities: Command registration, event listener setup, configuration management
  • Size: Reduced from 220 → 81 lines (63% reduction)

2. Commands Layer (src/commands/)

  • Purpose: VS Code command handlers and user interaction logic
  • Components:
    • minifyCommand.ts - Unified command logic with processDocument() core function
    • index.ts - Command exports with comprehensive documentation

3. Services Layer (src/services/)

  • Purpose: Business logic and external API integrations
  • Components:
    • minificationService.ts - Toptal API communication with error handling
    • fileService.ts - File system operations and filename utilities
    • index.ts - Service exports with module documentation

4. Utils Layer (src/utils/)

  • Purpose: Reusable validation and utility functions
  • Components:
    • validators.ts - File type and content validation with user feedback
    • index.ts - Utility exports with module documentation

Benefits of Modular Architecture

✅ Separation of Concerns

  • Each module has a single responsibility
  • Clear boundaries between UI logic, business logic, and utilities
  • Easier to locate and modify specific functionality

✅ Code Reusability

  • No duplicate validation or API logic between commands
  • Shared utilities across different command handlers
  • Consistent error handling patterns

✅ Enhanced Testability

  • Pure functions easier to unit test
  • Isolated business logic can be tested independently
  • Mocking external dependencies is straightforward

✅ Improved Maintainability

  • 63% reduction in main file complexity
  • Self-documenting code with comprehensive JSDoc
  • Clear module dependencies and exports

✅ Better Developer Experience

  • IntelliSense support for all module functions
  • Type safety with proper interfaces
  • Consistent coding patterns throughout

Data Flow

User Action (Command/Keybinding/Context Menu)
    ↓
Command Handler (commands/minifyCommand.ts)
    ↓
Validation (utils/validators.ts)
    ↓
Minification Service (services/minificationService.ts)
    ↓
File Operations (services/fileService.ts)
    ↓
User Feedback (VS Code Notifications)

Module Dependencies

extension.ts
    ↓
commands/index.ts
    ↓
commands/minifyCommand.ts
    ↓
├── utils/validators.ts
├── services/minificationService.ts
└── services/fileService.ts

Error Handling Strategy

Layered Error Handling

  1. Validation Layer: Input validation with user-friendly messages
  2. Service Layer: API error handling with retry logic and specific error codes
  3. Command Layer: Coordination and user notification
  4. Extension Layer: Global error catching and logging

User Experience Focus

  • All errors show appropriate VS Code notifications
  • Context-aware error messages (file type, network issues, API limits)
  • Graceful degradation when services are unavailable

Configuration Management

Centralized Settings

  • All configuration accessed through vscode.workspace.getConfiguration()
  • Settings validated at the point of use
  • Default values provided for all optional settings

Dynamic Configuration

  • Settings can be changed without extension restart
  • Configuration changes take effect immediately
  • Per-workspace and global configuration support

Performance Optimizations

Lazy Loading

  • Modules loaded only when needed
  • Webpack bundling for optimal distribution size
  • Tree shaking removes unused code

API Efficiency

  • Request debouncing for rapid user actions
  • Response caching where appropriate
  • Timeout handling for slow network conditions

Future Extensibility

Plugin Architecture Ready

  • Service layer can be extended with new minification providers
  • Command layer supports additional file types
  • Validation layer can accommodate new file formats

Internationalization Support

  • All user-facing strings externalized to .nls files
  • Message formatting prepared for multiple languages
  • Locale-specific error handling

Last Updated: October 16, 2025 Extension Version: 1.0.0