# afrit-bagani/vscode-icons architecture

> Architecture diagram of the GitHub repository afrit-bagani/vscode-icons, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/afrit-bagani/vscode-icons
- Repository: https://github.com/afrit-bagani/vscode-icons

## Overview

##### Architectural Overview
- The extension runs entirely in VSCode’s Extension Host process. There is no external server or database—everything is packaged and executed locally.
- There are two main runtime phases:
a. Activation & Initialization
b. Theme Generation & Event Handling

A. VSCode Shell
- Extension Host (host process)
- VSCode API (commands, window, workspace, configuration)

B. Extension Core
- extensionManager.ts – entry point, handles activation/deactivation
- compositionRootService.ts – dependency injection container, wires services
- configManager.ts – reads/writes user settings
- i18n.languageResourceManager – loads localized strings via Crowdin resources
- projectAutoDetectionManager (pad) – inspects workspace to auto‑apply presets
- notificationManager – shows VSCode notifications
- fsAsync, errorHandler, debugger – common utilities

- iconsManifest sources (default and custom definitions)
- locale/ – translation files for UI strings

D. Dev/Build Toolchain (side‑component)
- webpack.config.ts – bundles TS to JS
- build.ts, bundle.ts – CLI scripts for packaging
- npm scripts, tsconfig.json
- Continuous Integration workflows (GitHub Actions)

##### Component Interactions & Data Flow
- On Extension Activation (VSCode fires ‘activate’):
→ extensionManager invokes compositionRootService
→ Services (configManager, i18n, iconsManifest) are instantiated
→ Calls VSCode API (`vscode.window.registerFileIconTheme`) to apply theme

- At Runtime:
- Listens to workspace events (onDidChangeConfiguration, onDidChangeWorkspaceFolders) → configManager emits updates → manifest rebuilt → VSCode API called again

- Notifications and errors bubble via notificationManager and errorHandler to the user.

##### Architectural Patterns & Principles
- Inversion of Control / Dependency Injection: compositionRootService centralizes wiring.
- Separation of Concerns:
- Core services (config, i18n, manifest building) are decoupled.
- Models in `src/models` represent domain objects (extensions, contributions, settings).
- Single Responsibility: each folder (common, services, models, tools) houses a distinct layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% VSCode Shell
    subgraph "VSCode Shell"
        direction TB
        VSCodeAPI["VSCode API\n(commands, window, workspace)"]:::host
        ExtHost["Extension Host"]:::host
    end

    %% Extension Core
    subgraph "Extension Core"
        direction TB
        EntryPoint["Extension Entry Point\n(src/index.ts)"]:::core
        ExtManager["Extension Manager\n(src/app/extensionManager.ts)"]:::core
        CompositionRoot["Composition Root Service\n(src/services/compositionRootService.ts)"]:::core
        subgraph "Services"
            direction TB
            ConfigMgr["Configuration Manager\n(src/configuration/configManager.ts)"]:::core
            I18nMgr["i18n Language Resource Manager\n(src/i18n/languageResourceManager.ts)"]:::core
            ManifestBuilder["Icon Manifest Builder\n(src/iconsManifest/manifestBuilder.ts)"]:::core
            IconsGen["Icon Generator\n(src/iconsManifest/iconsGenerator.ts)"]:::core
            ManifestReader["Manifest Reader\n(src/iconsManifest/manifestReader.ts)"]:::core
            CustomsMerger["Customs Merger\n(src/iconsManifest/customsMerger.ts)"]:::core
            SuppExt["Supported Extensions Definitions\n(src/iconsManifest/supportedExtensions.ts)"]:::core
            SuppFold["Supported Folders Definitions\n(src/iconsManifest/supportedFolders.ts)"]:::core
            ManifestIndex["Icons Manifest Index\n(src/iconsManifest/index.ts)"]:::core
            PADMgr["Project Auto-Detection Manager\n(src/pad/projectAutoDetectionManager.ts)"]:::core
            NotifMgr["Notification Manager\n(src/notification/notificationManager.ts)"]:::core
            FsAsync["fsAsync Utility\n(src/common/fsAsync.ts)"]:::core
            ErrorH["Error Handler\n(src/common/errorHandler.ts)"]:::core
            DebugUtil["Debugger Utility\n(src/common/debugger.ts)"]:::core
            VSCodeMgr["VSCode API Host/Manager\n(src/vscode/vscodeManager.ts)"]:::core
        end
    end

    %% Icon Data
    subgraph "Icon Data"
        direction TB
        IconsFolder["icons/ Folder"]:::data
        LocaleFiles["locale/ Files\n(locale/lang/, locale/package/)"]:::data
    end

    %% Build Toolchain
    subgraph "Build Toolchain"
        direction TB
        Webpack["webpack.config.ts"]:::build
        BuildScript["build.ts\n(src/tools/build.ts)"]:::build
        BundleScript["bundle.ts\n(src/tools/bundle.ts)"]:::build
        TsConfig["tsconfig.json"]:::build
        CI["CI Workflows\n(GitHub Actions)"]:::build
    end

    %% Activation & Initialization Flow
    ExtHost -->|activate| EntryPoint
    EntryPoint --> ExtManager
    ExtManager --> CompositionRoot
    CompositionRoot --> ConfigMgr
    CompositionRoot --> I18nMgr
    CompositionRoot --> ManifestBuilder
    CompositionRoot --> PADMgr
    CompositionRoot --> NotifMgr
    CompositionRoot --> VSCodeMgr
    CompositionRoot --> FsAsync
    CompositionRoot --> ErrorH
    CompositionRoot --> DebugUtil

    %% Manifest Building Flow
    ManifestBuilder --> ManifestReader
    ManifestBuilder --> CustomsMerger
    ManifestBuilder --> SuppExt
    ManifestBuilder --> SuppFold
    ManifestBuilder --> ManifestIndex
    ManifestBuilder --> IconsGen
    IconsGen --> IconsFolder
    I18nMgr --> LocaleFiles

    ManifestBuilder -->|build theme| VSCodeAPI

    %% Runtime Event Handling
    VSCodeAPI -->|onDidChangeConfiguration| ConfigMgr
    ConfigMgr -->|update| ManifestBuilder
    VSCodeAPI -->|onDidChangeWorkspaceFolders| PADMgr
    PADMgr -->|detect presets| ManifestBuilder

    %% Notifications and Errors
    ErrorH -->|handle| NotifMgr
    NotifMgr --> VSCodeAPI

    %% Build Pipeline
    BuildScript --> Webpack
    BundleScript --> Webpack
    Webpack --> TsConfig
    Webpack --> CI

    %% Styling
    classDef host fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef core fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef data fill:#ffe082,stroke:#ff8f00,stroke-width:1px
    classDef build fill:#c8e6c9,stroke:#388e3c,stroke-width:1px

    %% Click Events
    click ExtManager "https://github.com/afrit-bagani/vscode-icons/blob/master/src/app/extensionManager.ts"
    click CompositionRoot "https://github.com/afrit-bagani/vscode-icons/blob/master/src/services/compositionRootService.ts"
    click ConfigMgr "https://github.com/afrit-bagani/vscode-icons/blob/master/src/configuration/configManager.ts"
    click I18nMgr "https://github.com/afrit-bagani/vscode-icons/blob/master/src/i18n/languageResourceManager.ts"
    click ManifestBuilder "https://github.com/afrit-bagani/vscode-icons/blob/master/src/iconsManifest/manifestBuilder.ts"
    click IconsGen "https://github.com/afrit-bagani/vscode-icons/blob/master/src/iconsManifest/iconsGenerator.ts"
    click ManifestReader "https://github.com/afrit-bagani/vscode-icons/blob/master/src/iconsManifest/manifestReader.ts"
    click CustomsMerger "https://github.com/afrit-bagani/vscode-icons/blob/master/src/iconsManifest/customsMerger.ts"
    click SuppExt "https://github.com/afrit-bagani/vscode-icons/blob/master/src/iconsManifest/supportedExtensions.ts"
    click SuppFold "https://github.com/afrit-bagani/vscode-icons/blob/master/src/iconsManifest/supportedFolders.ts"
    click ManifestIndex "https://github.com/afrit-bagani/vscode-icons/blob/master/src/iconsManifest/index.ts"
    click PADMgr "https://github.com/afrit-bagani/vscode-icons/blob/master/src/pad/projectAutoDetectionManager.ts"
    click NotifMgr "https://github.com/afrit-bagani/vscode-icons/blob/master/src/notification/notificationManager.ts"
    click FsAsync "https://github.com/afrit-bagani/vscode-icons/blob/master/src/common/fsAsync.ts"
    click ErrorH "https://github.com/afrit-bagani/vscode-icons/blob/master/src/common/errorHandler.ts"
    click DebugUtil "https://github.com/afrit-bagani/vscode-icons/blob/master/src/common/debugger.ts"
    click VSCodeMgr "https://github.com/afrit-bagani/vscode-icons/blob/master/src/vscode/vscodeManager.ts"
    click EntryPoint "https://github.com/afrit-bagani/vscode-icons/blob/master/src/index.ts"
    click Webpack "https://github.com/afrit-bagani/vscode-icons/blob/master/webpack.config.ts"
    click BuildScript "https://github.com/afrit-bagani/vscode-icons/blob/master/src/tools/build.ts"
    click BundleScript "https://github.com/afrit-bagani/vscode-icons/blob/master/src/tools/bundle.ts"
```
