# mbehr1/fishbone architecture

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

- Interactive diagram: https://gitdiagram.com/mbehr1/fishbone
- Repository: https://github.com/mbehr1/fishbone

## Overview

##### Project type and purpose
- It includes a backend-side VS Code extension (TypeScript) and a frontend-side embedded webview app (React) plus supporting documentation and tests.

##### File structure
Top-level directories and files:
- src/extension: VS Code extension code (activation, commands, providers, formatters, AI integrations, notebook, FS).
- src/test: unit and integration tests for the extension.
- docs/fishbone: Docusaurus site for public documentation.
- Configuration files: tsconfig.json, esbuild.mjs (build extension or bundle webview), .github/workflows (CI/CD), BUILD.md.
- Package manifests: package.json (root), src/webview/package.json (webview dependencies).
- Other: types/ (d.ts), static images, db.json for sample data, license, changelog.

##### README for additional insights
- Technologies: VS Code Extension API, TypeScript, React, Material-UI, fishbone-chart, js-yaml, jsonpath.
- External integrations: REST services, other extensions (dlt-logs).

##### Main components and their interactions
a. VS Code Host & Extension Host
- The extension registers commands (e.g. New Fishbone), file watchers for .fba files, language-configuration, grammar.
- It implements providers:
- FileSystemProvider to read/write .fba files
- NotebookProvider for fishbone as a notebook
- AIProvider for hints/history/DSL helpers
- Format/edit/render utilities
- It launches a WebviewPanel and communicates via VS Code’s message passing (postMessage).
b. Embedded Webview App (React)
- Calls back to extension host for backend tasks (e.g. REST queries).
c. External Services
- Optional REST endpoints (JIRA, custom servers), and DLT-logs extension APIs, for data fetching.
d. Persistence Layer
- Storage of .fba files (YAML or JSON inside), allowing undo/redo via VS Code’s built-in API.
e. Documentation Site
- Docusaurus “docs/fishbone” built and hosted via GitHub Pages, separate from core runtime.

##### Architectural patterns and design principles
- Modular separation: extension logic vs UI logic.
- Message-based communication between host and webview.
- Provider pattern: FileSystem, Notebook, AI.
- React component hierarchy for fishbone chart, summary table, dialogs.
- CI/CD pipelines via GitHub Actions for lint, tests, release, docs deployment.
- TypeScript for strong typing, custom type declarations in types/.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors and Applications
    VSCodeApp["VS Code Application"]:::external

    subgraph "Extension Host (Backend)" 
        direction TB
        ExtActivation["Activation & Commands Module"]:::backend
        Constants["Constants"]:::backend
        FSProvider["FileSystemProvider"]:::backend
        NotebookProvider["NotebookProvider"]:::backend
        AIProvider["AIProvider"]:::backend
        AITools["AI Tools & History"]:::backend
        Formatters["Formatters & Renderers"]:::backend
        Util["Utility Functions"]:::backend
    end

    subgraph "Embedded Webview Panel (Frontend)"
        direction TB
        ReactIndex["React Entry"]:::frontend
        ReactApp["App Component"]:::frontend
        FishboneChart["Fishbone Chart Component"]:::frontend
        ChartCSS["fishboneChart.css"]:::frontend
        SummaryTable["Summary Table UI"]:::frontend
        Dialogs["Dialogs & Controls"]:::frontend
        ExternalUI["External REST & DLT-Logs UI"]:::frontend
        DataProviderUI["Data Provider Interfaces"]:::frontend
        UIUtils["Supporting UI Utilities"]:::frontend
    end

    subgraph "External Services" 
        RESTServices["External REST Services\n(JIRA, DLT-Logs)"]:::external
    end

    subgraph "File System" 
        FBAFiles[".fba Files Store"]:::infra
    end

    subgraph "Documentation Site" 
        Docs["Docusaurus Site"]:::infra
    end

    subgraph "CI/CD Pipeline" 
        CICD["GitHub Actions"]:::infra
        BuildScript["Build & Bundle Script"]:::infra
    end

    %% Relationships
    VSCodeApp -->|activates extension| ExtActivation
    ExtActivation -->|registers commands/providers| Constants
    ExtActivation -->|opens Webview| ReactIndex

    ReactIndex --> ReactApp
    ReactApp --> FishboneChart
    ReactApp --> SummaryTable
    ReactApp --> Dialogs
    ReactApp --> ExternalUI
    ReactApp --> DataProviderUI
    ReactApp --> UIUtils
    ReactApp -->|postMessage: read/write .fba| FSProvider
    ReactApp -->|postMessage: notebook ops| NotebookProvider
    ReactApp -->|postMessage: AI hints| AIProvider

    FSProvider -->|read/write| FBAFiles
    NotebookProvider -->|notebook storage| FBAFiles
    AIProvider --> AITools
    AITools -->|use utilities| Util
    Formatters --> Util

    ExtActivation -->|REST API call| RESTServices
    RESTServices -->|response| ExtActivation

    CICD -->|runs build| BuildScript
    BuildScript --> ReactIndex
    BuildScript --> Formatters

    CICD -->|deploy docs| Docs
    CICD -->|publish extension| VSCodeApp

    %% Click Events
    click ExtActivation "https://github.com/mbehr1/fishbone/blob/main/src/extension/extension.ts"
    click Constants "https://github.com/mbehr1/fishbone/blob/main/src/extension/constants.ts"
    click FSProvider "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbaFSProvider.ts"
    click NotebookProvider "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbaNotebookProvider.ts"
    click AIProvider "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbAIProvider.ts"
    click AITools "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbAiTools.ts"
    click AITools "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbAiHistory.ts"
    click AITools "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbAiFishboneContext.tsx"
    click AITools "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbAiDltDocContext.tsx"
    click Formatters "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbaFormat.ts"
    click Formatters "https://github.com/mbehr1/fishbone/blob/main/src/extension/fbaNBRQRenderer.ts"
    click Util "https://github.com/mbehr1/fishbone/blob/main/src/extension/util.ts"
    click ReactIndex "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/index.js"
    click ReactApp "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/App.js"
    click FishboneChart "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/fishbone/fishboneChart.js"
    click ChartCSS "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/fishbone/fishboneChart.css"
    click SummaryTable "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/summary/table.js"
    click SummaryTable "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/summary/tableToolbar.js"
    click Dialogs "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/dataProviderEditDialog.js"
    click Dialogs "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/summaryDialog.js"
    click Dialogs "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/textFieldEditDialog.js"
    click ExternalUI "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/dltRestQueryManual.js"
    click ExternalUI "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/dltFilterAssistant.js"
    click DataProviderUI "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/dataProvider.js"
    click DataProviderUI "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/summary/dataProvider.js"
    click UIUtils "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/multiStateBox.js"
    click UIUtils "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/onBlurInputBase.js"
    click UIUtils "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/utils/json5.js"
    click UIUtils "https://github.com/mbehr1/fishbone/blob/main/src/webview/src/components/utils/markdown.js"
    click Docs "https://github.com/mbehr1/fishbone/tree/main/docs/fishbone/"
    click CICD "https://github.com/mbehr1/fishbone/tree/main/.github/workflows/"
    click BuildScript "https://github.com/mbehr1/fishbone/blob/main/esbuild.mjs"

    %% Styles
    classDef backend fill:#cce5ff,stroke:#3399ff
    classDef frontend fill:#e6ffe6,stroke:#33cc33
    classDef external fill:#f2f2f2,stroke:#999999,stroke-dasharray: 2 2
    classDef infra fill:#fff2cc,stroke:#ffcc00
```
