# bchiang7/halcyon-vscode architecture

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

- Interactive diagram: https://gitdiagram.com/bchiang7/halcyon-vscode
- Repository: https://github.com/bchiang7/halcyon-vscode

## Overview

##### Project type and purpose
- It is *not* a multi-service web app but a single plugin package that plugs into the VS Code extension host.

##### File structure
- Top-level metadata and config:
- package.json – extension manifest (name, publisher, version, contributions)
- .vscodeignore – files excluded from the VSIX
- LICENSE, README.md, vsc-extension-quickstart.md
- prettier.config.js, .eslintrc, .gitignore
- Assets and resources:
- images/logo.sketch, images/demo.png – design assets shown in README
- Demo folder: a sandbox with sample code files in various languages, to showcase the theme in action.

##### Key insights from the README
- Installation flows (VS Code marketplace vs. manual).
- The extension’s sole contribution point is the `colorTheme` in package.json, pointing to the JSON in themes/.
- No background services or server components—this is purely a read-only resource bundle.

##### Main components
a. VS Code Host Components
1. Extension Manager – discovers installed extensions
2. Extension Host Process – loads and activates the Halcyon extension
b. Halcyon Extension Package
1. package.json (manifest)
4. demo/ (sample code, outside VSIX in source tree)
c. External Entities
1. VS Code Marketplace (source of installation)

##### Component interactions and data flow
- Marketplace → downloads .vsix (package)
↳ User’s VS Code Extension Manager
- Extension Manager → Extension Host
- Demo files (optional)—user previews theme on various language grammars.

##### Architectural patterns and design principles
- Plugin/Extension Architecture: Extension Host + manifest-driven contributions.
- Resource-only delivery: no custom code, only JSON configuration.
- Separation of concerns:
- package.json for metadata
- themes JSON for actual styling
- README + demo for documentation and preview

##### Essential elements, no over-splitting
- Do *not* invent microservices or unnecessary layers.
- Keep to *four* or *five* logical blocks (Marketplace, Extension Host, Theme JSON, Theme Engine, UI Renderer).
- Manifest → contribution → rendering path clearly.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Entities"
        Market["VS Code Marketplace"]:::external
        User["End User's Editor UI"]:::external
    end

    subgraph "VS Code Core"
        ExtManager["Extension Manager"]:::core
        ExtHost["Extension Host Process"]:::core
        ThemeEngine["Theme Engine"]:::core
    end

    subgraph "Halcyon Extension Package"
        pkg["Extension Manifest (package.json)"]:::artifact
        theme["Theme Definition (halcyon-color-theme.json)"]:::artifact
        ignore["Ignore Config (.vscodeignore)"]:::artifact
        readme["Documentation (README.md)"]:::artifact
        quick["Quickstart Guide (vsc-extension-quickstart.md)"]:::artifact
        assets["Design Asset (logo.sketch)"]:::artifact
        demo["Demo Samples (demo/)"]:::artifact
        eslint["Lint Config (.eslintrc)"]:::artifact
        prettier["Formatting Config (prettier.config.js)"]:::artifact
        gitignore["Gitignore (.gitignore)"]:::artifact
    end

    subgraph "Rendering Targets"
        Workbench["Workbench UI"]:::core
        Syntax["Editor Syntax Highlighter"]:::core
        Preview["Editor Preview"]:::core
    end

    Market --> ExtManager
    ExtManager --> ExtHost
    pkg --> ExtHost
    ExtHost --> ThemeEngine
    theme --> ThemeEngine
    ThemeEngine --> Workbench
    ThemeEngine --> Syntax
    demo --> Preview
    Preview --> User

    click pkg "https://github.com/bchiang7/halcyon-vscode/blob/main//package.json"
    click theme "https://github.com/bchiang7/halcyon-vscode/blob/main//themes/halcyon-color-theme.json"
    click ignore "https://github.com/bchiang7/halcyon-vscode/blob/main//.vscodeignore"
    click readme "https://github.com/bchiang7/halcyon-vscode/blob/main//README.md"
    click quick "https://github.com/bchiang7/halcyon-vscode/blob/main//vsc-extension-quickstart.md"
    click assets "https://github.com/bchiang7/halcyon-vscode/blob/main//images/logo.sketch"
    click demo "https://github.com/bchiang7/halcyon-vscode/tree/main//demo/"
    click eslint "https://github.com/bchiang7/halcyon-vscode/blob/main//.eslintrc"
    click prettier "https://github.com/bchiang7/halcyon-vscode/blob/main//prettier.config.js"
    click gitignore "https://github.com/bchiang7/halcyon-vscode/blob/main//.gitignore"

    classDef core fill:#DDDDDD,stroke:#888,stroke-width:1px;
    classDef artifact fill:#BBBBFF,stroke:#6688CC,stroke-width:1px;
    classDef external fill:#CCFFCC,stroke:#88AA88,stroke-width:1px;
```
