# janisdd/vscode-edit-csv architecture

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

- Interactive diagram: https://gitdiagram.com/janisdd/vscode-edit-csv
- Repository: https://github.com/janisdd/vscode-edit-csv

## Overview

##### Project Type and Purpose
- This is a VS Code extension (plus an optional standalone web app) that provides an Excel-like UI for editing CSV/TSV files.
- Core idea: The extension hosts a Webview in VS Code. The Webview runs browser‐side code (HTML/TS/CSS) that displays and edits the CSV in a Handsontable grid. The extension backend reads/writes the actual CSV file and mediates communication to/from the Webview.

##### High-Level File Structure
- /src: extension backend TypeScript (commands, file I/O, VS Code API integration).
- /csvEditorHtml: Webview frontend source and standalone web-app source (HTML, TS, CSS, build scripts, tests).
- /out: compiled extension backend JavaScript.
- /thirdParty: packaged third-party libs for the Webview (Papaparse, Handsontable, Mousetrap, Big.js, regression.js, etc.).

##### Key Components
a. VS Code Host
- VS Code Extension Host process
- Presents command palette entries (“Edit as CSV”, “Edit With Config”)
b. Extension Backend
- extension.ts: registers commands, listens for Webview messages
- configurationHelper.ts: builds configuration JSON
- instanceManager.ts: tracks open editor instances and URIs
- getHtml.ts: inlines the Webview’s HTML template with scripts and styles
- util.ts: helpers for chunking large files, handling settings
c. File System
- Reads the CSV/TSV file from disk
- Writes back on “Apply” or “Apply and Save”
d. Webview Frontend
- index.html + injected config
- main.ts/browser.ts, ui.ts: bootstraps the Handsontable grid
- io.ts: handles postMessage to/from the extension
- autoFill.ts, progressbar.ts, findWidget.ts: UI modules
- CSS files: themes (light, dark, high_contrast), settingsOverwrite.css
- thirdParty libs (Papaparse, Handsontable, etc.)
e. Message Bus
- Extension → Webview: webview.postMessage({ chunks, config })
- Webview → Extension: vscode.postMessage({ csvText, command })

##### Relationships and Data Flow
1. User issues “Edit as CSV” in VS Code
2. Extension reads file, splits it into chunks if large
3. Extension loads Webview, injects HTML + scripts + config
4. Extension calls webview.postMessage() with file chunks + config
5. Webview receives message, reassembles text, uses Papaparse to parse CSV → model
6. Handsontable renders the grid; user edits cells
7. On “Apply”: Webview serializes grid → CSV text, posts message back
8. Extension receives message, concatenates text, writes to disk
9. On “Apply and Save”: extension also issues file.save()
10. Commands like “Read again” re-inject saved config without re-reading disk

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Backend (Node/VS Code API) vs. Frontend (Browser/Webview)
- InstanceManager (state), ConfigurationHelper (config), IO vs. UI modules
- Message-Driven Integration: clear, one-way and two-way postMessage channels
- Modular Frontend: discrete UI features (auto-fill, find widget, progress bar)
- Single Source of Truth for configuration: injected JSON, read-only in Webview

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% VS Code Host
    subgraph "VS Code Host"
        direction TB
        HostProcess["VS Code Extension Host"]:::host
        CommandPalette["Commands: Edit as CSV / Edit With Config"]:::host
    end

    %% Extension Backend
    subgraph "Extension Backend"
        direction TB
        ExtEntry["extension.ts"]:::backend
        ConfigHelper["configurationHelper.ts"]:::backend
        InstanceMgr["instanceManager.ts"]:::backend
        HTMLInliner["getHtml.ts"]:::backend
        Utils["util.ts"]:::backend
        Compiled["out/extension.js"]:::backend
    end

    %% File System
    subgraph "File System" 
        direction TB
        FileSys[(File System)]:::fs
    end

    %% Webview Frontend
    subgraph "Webview Frontend"
        direction TB
        IndexHTML["index.html"]:::frontend
        PreDOM["beforeDomLoaded.ts"]:::frontend
        Bootstrap["main.ts"]:::frontend
        IO["io.ts"]:::frontend
        UI["ui.ts"]:::frontend
        AutoFill["autoFill.ts"]:::frontend
        ProgressBar["progressbar.ts"]:::frontend
        FindWidget["findWidget.ts"]:::frontend
        CSSThemes["CSS Themes"]:::frontend
        SettingsCSS["settingsOverwrite.css"]:::frontend
        subgraph "CSS Themes"
            lightCSS["light.css"]:::frontend
            darkCSS["dark.css"]:::frontend
            highContrastCSS["high_contrast.css"]:::frontend
        end
    end

    %% Standalone Web App
    subgraph "Standalone Web App"
        direction TB
        BrowserIndex["indexBrowser.html"]:::frontend
        PreDOMBrowser["beforeDomLoadedBrowser.ts"]:::frontend
        PostDOMBrowser["afterDomLoadedBrowser.ts"]:::frontend
        BrowserCSS["browser.css"]:::frontend
        BuildScript["build.ts"]:::frontend
        ThirdPartyBrowser["third-party"]:::external
    end

    %% Third-Party Libraries (packaged)
    subgraph "Packaged Third-Party Libs"
        direction TB
        BigJS["big.js"]:::external
        FontAwesome["fortawesome"]:::external
        HandsontableLib["handsontable"]:::external
        MousetrapLib["mousetrap"]:::external
        PapaParseLib["papaparse"]:::external
        RegressionLib["regression"]:::external
        DayJS["toFormat/day.js"]:::external
    end

    %% Data Flows
    CommandPalette -->|"invoke command"| ExtEntry
    ExtEntry -->|"reads file"| FileSys
    ExtEntry --> HTMLInliner
    HTMLInliner --> IndexHTML
    HTMLInliner --> Bootstrap
    HTMLInliner --> PreDOM
    HTMLInliner --> CSSThemes
    ExtEntry -->|"webview.postMessage(chunks, config)"| IO
    IO -->|"/json parse"| PapaParseLib
    PapaParseLib --> UI
    UI --> AutoFill
    UI --> ProgressBar
    UI --> FindWidget
    Bootstrap -->|"user edits"| UI
    UI -->|"serialize CSV"| IO
    IO -->|"vscode.postMessage"| ExtEntry
    ExtEntry -->|"writes file"| FileSys

    %% Standalone Flow
    BrowserIndex --> PreDOMBrowser
    PreDOMBrowser --> BrowserCSS
    PreDOMBrowser --> Bootstrap
    BuildScript --> BrowserIndex

    %% External libs used in Webview
    IO --> PapaParseLib
    UI --> HandsontableLib
    UI --> MousetrapLib
    AutoFill --> RegressionLib
    AutoFill --> DayJS
    Bootstrap --> BigJS

    %% Click Events
    click ExtEntry "https://github.com/janisdd/vscode-edit-csv/blob/master/src/extension.ts"
    click ConfigHelper "https://github.com/janisdd/vscode-edit-csv/blob/master/src/configurationHelper.ts"
    click InstanceMgr "https://github.com/janisdd/vscode-edit-csv/blob/master/src/instanceManager.ts"
    click HTMLInliner "https://github.com/janisdd/vscode-edit-csv/blob/master/src/getHtml.ts"
    click Utils "https://github.com/janisdd/vscode-edit-csv/blob/master/src/util.ts"
    click Compiled "https://github.com/janisdd/vscode-edit-csv/blob/master/out/extension.js"
    click IndexHTML "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/index.html"
    click Bootstrap "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/main.ts"
    click PreDOM "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/beforeDomLoaded.ts"
    click IO "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/io.ts"
    click UI "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/ui.ts"
    click AutoFill "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/autoFill.ts"
    click ProgressBar "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/progressbar.ts"
    click FindWidget "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/findWidget.ts"
    click lightCSS "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/light.css"
    click darkCSS "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/dark.css"
    click highContrastCSS "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/high_contrast.css"
    click SettingsCSS "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/settingsOverwrite.css"
    click BrowserIndex "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/browser/indexBrowser.html"
    click PreDOMBrowser "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/browser/beforeDomLoadedBrowser.ts"
    click PostDOMBrowser "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/browser/afterDomLoadedBrowser.ts"
    click BrowserCSS "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/browser/browser.css"
    click BuildScript "https://github.com/janisdd/vscode-edit-csv/blob/master/csvEditorHtml/browser/build/build.ts"
    click ThirdPartyBrowser "https://github.com/janisdd/vscode-edit-csv/tree/master/csvEditorHtml/browser/third-party"
    click BigJS "https://github.com/janisdd/vscode-edit-csv/blob/master/thirdParty/big.js"
    click FontAwesome "https://github.com/janisdd/vscode-edit-csv/tree/master/thirdParty/fortawesome"
    click HandsontableLib "https://github.com/janisdd/vscode-edit-csv/tree/master/thirdParty/handsontable"
    click MousetrapLib "https://github.com/janisdd/vscode-edit-csv/tree/master/thirdParty/mousetrap"
    click PapaParseLib "https://github.com/janisdd/vscode-edit-csv/tree/master/thirdParty/papaparse"
    click RegressionLib "https://github.com/janisdd/vscode-edit-csv/tree/master/thirdParty/regression"
    click DayJS "https://github.com/janisdd/vscode-edit-csv/blob/master/thirdParty/toFormat/day.js"

    %% Styles
    classDef host fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D5F5E3,stroke:#333,stroke-width:1px
    classDef frontend fill:#FCF3CF,stroke:#333,stroke-width:1px
    classDef external fill:#EBEDEF,stroke:#333,stroke-width:1px
    classDef fs fill:#FADBD8,stroke:#333,stroke-width:1px
```
