# paranext/paranext-extension-template architecture

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

- Interactive diagram: https://gitdiagram.com/paranext/paranext-extension-template
- Repository: https://github.com/paranext/paranext-extension-template

## Overview

##### Project Type and Purpose
- This is neither a web server nor a microservice‐based system, but an **extension template** for the Platform.Bible desktop application.
- It provides the skeleton for:
- an extension “main” process (TypeScript code registered via the PAPI)
- optional React‐based WebViews
- asset and contribution metadata
- build & packaging pipelines

##### File Structure
- `src/` (entry point `src/main.ts`, `.web-view.tsx` React UIs, type definitions)
- `contributions/` (menus, settings, themes JSON)
- `lib/` (helper scripts for version bumping, Git utilities)
- `webpack/` (multiple Webpack configs & a custom plugin for resolving WebViews)
- root configs: `package.json`, `manifest.json`, TypeScript, Tailwind, PostCSS, ESLint, Stylelint
- CI: `.github/workflows/publish.yml` for releases

##### Core Components
a. **Source Code & Metadata**
- `src/` (main.ts + WebView code + types)
- `assets/` (images, localized descriptions)
- `contributions/` JSON definitions
- `manifest.json` & `package.json` (extension identity, dependencies)
b. **Build System**
- **Webpack** with three configurations:
- Main process bundle (`webpack.config.main.ts`)
- Web‐View bundles (`webpack.config.web-view.ts`)
- Shared/base config (`webpack.config.base.ts`)
- **SWC‐loader** for TS→JS
- **PostCSS & Tailwind** for styling
- **Custom plugin** `web-view-resolve-webpack-plugin`
- **lib scripts** (`bump-versions.ts`, `git.util.ts`) invoked by npm scripts
c. **Continuous Integration / Release Pipeline**
- GitHub Actions (`publish.yml`)
- npm scripts: `build`, `watch`, `package`, `bump-versions`
- Output artifacts: `dist/` folder, zipped `release/`
d. **Runtime / Host Integration**
- **Platform.Bible** desktop application
- **Extension Loader** reads `manifest.json` and `dist/`
- **PAPI** (Platform API) bridges `main.ts` commands into host
- **WebViews** loaded via `papi-extension:` protocol
- **Contributions** modify host menus, settings, themes

##### Relationships & Data Flow
- **Developer** writes code/assets → commits to Git
↓
- **npm scripts** trigger Webpack + PostCSS + Tailwind → produce bundles in `dist/`
↓
- **GitHub Actions** (on release) call `npm run package` → zip + GitHub Release
↓
- **Platform.Bible** (runtime) loads extension from `dist/`:
- Registers commands/events via PAPI
- Renders UI in host windows or WebViews
- Applies `contributions/` JSON to host menus/settings

##### Architectural Patterns & Design Principles
- **Separation of Concerns**:
- Main (“backend”) vs. WebView (“frontend”) code
- Static assets & metadata vs. runtime logic
- **Plugin‐style extension**:
- Manifest-driven contributions
- Host‐plugin interface via PAPI
- **Modular bundling**:
- Multiple Webpack entries/configs
- Shared base config for consistency

##### Final Checklist
- Components: source modules, assets, webpack configs, CI, host
- Data flows: code → build → dist → runtime
- Architectural annotations: plugin‐style, separation of main vs. UI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer
    Developer["Developer"]:::actor

    %% Source & Metadata
    subgraph "Source & Metadata"
        direction TB
        MainProcess["Main Process (src/main.ts)"]:::code
        WebViewUI["WebView UIs (src/tailwind.css)"]:::code
        TypeDef1["TypeDef: paranext-extension-template.d.ts"]:::code
        TypeDef2["TypeDef: webpack-env.d.ts"]:::code
        AssetsDir["Assets Directory (assets/)"]:::metadata
        DisplayData["displayData.json"]:::metadata
        Description["description-en.md"]:::metadata
        Menus["menus.json"]:::metadata
        Settings["settings.json"]:::metadata
        ProjectSettings["projectSettings.json"]:::metadata
        Themes["themes.json"]:::metadata
        LocalizedStrings["localizedStrings.json"]:::metadata
        Manifest["manifest.json"]:::metadata
        Package["package.json"]:::metadata
    end

    %% Build System
    subgraph "Build System"
        direction TB
        WebpackBase["Webpack Base Config"]:::build
        WebpackMain["Webpack Main Bundle"]:::build
        WebpackWebView["Webpack WebView Bundles"]:::build
        CustomPlugin["web-view-resolve-webpack-plugin"]:::build
        WebpackUtil["webpack.util.ts"]:::build
        SWCLoader["SWC-loader"]:::build
        PostCSS["PostCSS"]:::build
        Tailwind["Tailwind"]:::build
        PostCSSConfig["postcss.config.ts"]:::build
        TailwindConfig["tailwind.config.ts"]:::build
        LibBump["bump-versions.ts"]:::build
        LibGit["git.util.ts"]:::build
        ESLint["ESLint Configs"]:::build
        Stylelint["Stylelint Configs"]:::build
        Prettier["Prettier Configs"]:::build
        TSConfig["TypeScript Configs"]:::build
        NpmScripts["npm Scripts"]:::build
    end

    %% Continuous Integration
    subgraph "CI / Release"
        direction TB
        CI["GitHub Actions (publish.yml)"]:::ci
        Dist["dist/ Artifacts"]:::artifact
        ReleaseZip["release/ Zip"]:::artifact
    end

    %% Runtime Integration
    subgraph "Runtime"
        direction TB
        Host["Platform.Bible Host"]:::host
        ExtLoader["Extension Loader"]:::host
        PAPI["PAPI Bridge"]:::host
        WebViewProto["WebViews (papi-extension:)"]:::host
        ApplyContrib["Apply Contributions"]:::host
    end

    %% Connections
    Developer -->|writes| MainProcess
    Developer -->|writes| WebViewUI
    Developer -->|writes| TypeDef1
    Developer -->|writes| TypeDef2
    Developer -->|adds| AssetsDir
    Developer -->|adds| DisplayData
    Developer -->|adds| Description
    Developer -->|defines| Menus
    Developer -->|defines| Settings
    Developer -->|defines| ProjectSettings
    Developer -->|defines| Themes
    Developer -->|defines| LocalizedStrings
    Developer -->|edits| Manifest
    Developer -->|edits| Package

    MainProcess -->|import| NpmScripts
    WebViewUI -->|import| NpmScripts
    TypeDef1 -->|typecheck| NpmScripts
    TypeDef2 -->|typecheck| NpmScripts

    AssetsDir -->|bundle| NpmScripts
    DisplayData -->|bundle| NpmScripts
    Description -->|bundle| NpmScripts
    Menus -->|bundle| NpmScripts
    Settings -->|bundle| NpmScripts
    ProjectSettings -->|bundle| NpmScripts
    Themes -->|bundle| NpmScripts
    LocalizedStrings -->|bundle| NpmScripts
    Manifest -->|include| NpmScripts
    Package -->|read| NpmScripts

    NpmScripts -->|uses| WebpackBase
    WebpackBase -->|extends| WebpackMain
    WebpackBase -->|extends| WebpackWebView
    WebpackMain -->|uses| SWCLoader
    WebpackWebView -->|uses| SWCLoader
    WebpackWebView -->|uses| CustomPlugin
    WebpackBase -->|uses| WebpackUtil
    NpmScripts -->|runs| PostCSS
    NpmScripts -->|runs| Tailwind
    PostCSS -->|config| PostCSSConfig
    Tailwind -->|config| TailwindConfig
    NpmScripts -->|runs| LibBump
    NpmScripts -->|runs| LibGit
    NpmScripts -->|runs| ESLint
    NpmScripts -->|runs| Stylelint
    NpmScripts -->|runs| Prettier
    NpmScripts -->|runs| TSConfig

    NpmScripts -->|outputs| Dist
    CI -->|on release runs| NpmScripts
    CI -->|packages| ReleaseZip

    Dist -->|loaded by| ExtLoader
    ReleaseZip -->|published to| CI

    ExtLoader -->|reads manifest| Manifest
    ExtLoader -->|registers commands| PAPI
    PAPI -->|executes main| MainProcess
    PAPI -->|loads| WebViewProto
    ApplyContrib -.->|injects| Host
    Menus -.-> ApplyContrib
    Settings -.-> ApplyContrib
    Themes -.-> ApplyContrib
    LocalizedStrings -.-> ApplyContrib

    ExtLoader -->|applies| ApplyContrib
    ExtLoader -->|mounts| Host

    %% Click Events
    click MainProcess "https://github.com/paranext/paranext-extension-template/blob/main/src/main.ts"
    click WebViewUI "https://github.com/paranext/paranext-extension-template/blob/main/src/tailwind.css"
    click TypeDef1 "https://github.com/paranext/paranext-extension-template/blob/main/src/types/paranext-extension-template.d.ts"
    click TypeDef2 "https://github.com/paranext/paranext-extension-template/blob/main/src/webpack-env.d.ts"
    click AssetsDir "https://github.com/paranext/paranext-extension-template/tree/main/assets/"
    click DisplayData "https://github.com/paranext/paranext-extension-template/blob/main/assets/displayData.json"
    click Description "https://github.com/paranext/paranext-extension-template/blob/main/assets/descriptions/description-en.md"
    click Menus "https://github.com/paranext/paranext-extension-template/blob/main/contributions/menus.json"
    click Settings "https://github.com/paranext/paranext-extension-template/blob/main/contributions/settings.json"
    click ProjectSettings "https://github.com/paranext/paranext-extension-template/blob/main/contributions/projectSettings.json"
    click Themes "https://github.com/paranext/paranext-extension-template/blob/main/contributions/themes.json"
    click LocalizedStrings "https://github.com/paranext/paranext-extension-template/blob/main/contributions/localizedStrings.json"
    click Manifest "https://github.com/paranext/paranext-extension-template/blob/main/manifest.json"
    click Package "https://github.com/paranext/paranext-extension-template/blob/main/package.json"
    click WebpackMain "https://github.com/paranext/paranext-extension-template/blob/main/webpack/webpack.config.main.ts"
    click WebpackWebView "https://github.com/paranext/paranext-extension-template/blob/main/webpack/webpack.config.web-view.ts"
    click WebpackBase "https://github.com/paranext/paranext-extension-template/blob/main/webpack/webpack.config.base.ts"
    click CustomPlugin "https://github.com/paranext/paranext-extension-template/blob/main/webpack/web-view-resolve-webpack-plugin.ts"
    click WebpackUtil "https://github.com/paranext/paranext-extension-template/blob/main/webpack/webpack.util.ts"
    click PostCSSConfig "https://github.com/paranext/paranext-extension-template/blob/main/postcss.config.ts"
    click TailwindConfig "https://github.com/paranext/paranext-extension-template/blob/main/tailwind.config.ts"
    click LibBump "https://github.com/paranext/paranext-extension-template/blob/main/lib/bump-versions.ts"
    click LibGit "https://github.com/paranext/paranext-extension-template/blob/main/lib/git.util.ts"
    click CI "https://github.com/paranext/paranext-extension-template/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef actor fill:#ffffff,stroke:#000000,stroke-width:1px
    classDef code fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef metadata fill:#d4edda,stroke:#155724,stroke-width:1px,shape:cylinder
    classDef build fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef ci fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef artifact fill:#d1ecf1,stroke:#0c5460,stroke-width:1px,shape:cylinder
    classDef host fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
