# paranext/paranext-core architecture

> Architecture diagram of the GitHub repository paranext/paranext-core, 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-core
- Repository: https://github.com/paranext/paranext-core

## Overview

##### Project type and purpose
- This is a full-stack, extensible desktop application built on Electron (“Platform.Bible”), combining:
- An Electron shell with Main and Renderer processes (TypeScript/React)
- An Extension Host that dynamically loads and runs extensions via a Plugin/API (PAPI)
- A .NET library (C#) for data providers and business logic
- A collection of first-party extensions in the `extensions` folder
- Shared libraries (`lib/platform-bible-react`, `lib/platform-bible-utils`, `lib/papi-dts`)

##### Top-level components (from the file tree)
- `.erb/configs`, scripts and build tools (Webpack, ESLint, etc.)
- `src/` – application source split into:
- `main/` – Electron main process and native services (RPC server, data-protection, dotnet provider)
- `extension-host/` – manages extensions, provides PAPI, RPC over WebSocket to Renderer
- `renderer/` – React UI, Web-View host, state/hooks, services bridging to PAPI
- `node/` – auxiliary Node services (file system, execution token)
- `client/` – RPC client code
- `shared/` – common models, services, RPC definitions used by all processes
- `c-sharp/` & `c-sharp-tests/` – .NET library code and tests, compiled separately
- `extensions/` – dozens of packaged first-party extensions, each with its own build (Webpack, TS, assets)
- `lib/` – published libraries (React components, utilities, PAPI type definitions)

##### Key interactions and architectural patterns
- Electron’s Main ⇄ Renderer via IPC and custom RPC WebSocket (RPC-server in Main, RPC-client in Renderer)
- Extension Host loaded into Main (separate process or thread) ⇄ Extensions via PAPI, also uses RPC/WebSocket
- Main spawns or calls .NET data provider (via `dotnet-data-provider.service-host`) for heavy processing
- Shared services and models unify communication contracts (RPC models, network objects, project-data providers)
- Renderer uses React + custom Hooks to consume PAPI services (data providers, settings, localization)
- Extensions register contributions (menus, settings, web views) through the Extension Host’s contribution service

##### Final checklist
- All primary processes/components labeled
- Notes on protocols (IPC, WebSocket-RPC, file-system, dotnet process spawn)
- Adequate detail: Main services, key React components, extension entry points, shared contracts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Electron Boundary
    subgraph "Electron Shell" 
        direction TB
        subgraph "Main Process"
            direction TB
            Main["Main Process"]:::main
            Services["Main Services"]:::main
            Preload["Preload Script"]:::main
        end
        subgraph "Renderer Process"
            direction TB
            Renderer["React UI"]:::renderer
            UIComponents["UI Components"]:::renderer
            PAPI_FE["PAPI Frontend"]:::renderer
            WSClient["WebSocket Client"]:::renderer
            Hooks["Renderer Hooks"]:::renderer
        end
    end

    %% Extension Host
    ExtensionHostCore["Extension Host Core"]:::extension
    ExtServices["Extension Host Services"]:::extension
    ExtModels["Extension Host Models/Types"]:::extension

    %% Extensions
    subgraph "Extensions"
        direction TB
        Extensions["First-Party Extensions"]:::extension
    end

    %% Node and .NET
    NodeServices["Node Auxiliary Services"]:::node
    Dotnet[".NET Data Provider"]:::dotnet
    DotnetTests[".NET Library Tests"]:::dotnet

    %% Shared Modules
    subgraph "Shared Modules & Contracts"
        direction TB
        SharedModels["Models & RPC Contracts"]:::shared
        SharedServices["Shared Services"]:::shared
        SharedUtils["Shared Utilities"]:::shared
    end

    %% Client RPC
    ClientRPC["Client RPC Services"]:::shared

    %% Published Libraries
    subgraph "Published Libraries"
        direction TB
        LibPAPI["PAPI Type Definitions"]:::shared
        LibReact["React Components"]:::shared
        LibUtils["Utilities"]:::shared
    end

    %% Connections
    Renderer -->|uses| UIComponents
    Renderer -->|calls| PAPI_FE
    PAPI_FE -->|WebSocket RPC| WSClient
    WSClient -->|RPC over IPC| Main
    Main -->|spawns| Dotnet
    Dotnet -->|tested by| DotnetTests
    Main -->|calls| NodeServices
    Main -->|loads| ExtensionHostCore
    ExtensionHostCore -->|provides API| ExtServices
    ExtensionHostCore -->|uses models| ExtModels
    ExtensionHostCore -->|hosts| Extensions
    Extensions -->|UI injected via WebView| Renderer
    SharedModels -.-> Main
    SharedModels -.-> Renderer
    SharedModels -.-> ExtensionHostCore
    Renderer -->|may use| ClientRPC
    ClientRPC -->|connects to| Main

    SharedModels --> SharedServices
    SharedServices --> SharedUtils
    SharedUtils --> Main
    SharedUtils --> Renderer
    SharedUtils --> ExtensionHostCore

    LibPAPI --> Renderer
    LibReact --> Renderer
    LibUtils --> Main

    %% Click Events
    click Main "https://github.com/paranext/paranext-core/blob/main/src/main/main.ts"
    click Services "https://github.com/paranext/paranext-core/tree/main/src/main/services"
    click Preload "https://github.com/paranext/paranext-core/blob/main/src/main/preload.ts"
    click ExtensionHostCore "https://github.com/paranext/paranext-core/blob/main/src/extension-host/extension-host.ts"
    click ExtServices "https://github.com/paranext/paranext-core/tree/main/src/extension-host/services"
    click ExtModels "https://github.com/paranext/paranext-core/tree/main/src/extension-host/data"
    click Extensions "https://github.com/paranext/paranext-core/tree/main/extensions/src"
    click Renderer "https://github.com/paranext/paranext-core/blob/main/src/renderer/index.tsx"
    click Renderer "https://github.com/paranext/paranext-core/blob/main/src/renderer/app.component.tsx"
    click UIComponents "https://github.com/paranext/paranext-core/tree/main/src/renderer/components"
    click PAPI_FE "https://github.com/paranext/paranext-core/blob/main/src/renderer/services/papi-frontend.service.ts"
    click WSClient "https://github.com/paranext/paranext-core/blob/main/src/renderer/services/renderer-web-socket.service.ts"
    click Hooks "https://github.com/paranext/paranext-core/tree/main/src/renderer/hooks"
    click ClientRPC "https://github.com/paranext/paranext-core/blob/main/src/client/services/rpc-client.ts"
    click ClientRPC "https://github.com/paranext/paranext-core/blob/main/src/client/services/web-socket.factory.ts"
    click NodeServices "https://github.com/paranext/paranext-core/tree/main/src/node/services"
    click SharedModels "https://github.com/paranext/paranext-core/tree/main/src/shared/models"
    click SharedServices "https://github.com/paranext/paranext-core/tree/main/src/shared/services"
    click SharedUtils "https://github.com/paranext/paranext-core/tree/main/src/shared/utils"
    click Dotnet "https://github.com/paranext/paranext-core/tree/main/c-sharp"
    click DotnetTests "https://github.com/paranext/paranext-core/tree/main/c-sharp-tests"
    click LibPAPI "https://github.com/paranext/paranext-core/tree/main/lib/papi-dts"
    click LibReact "https://github.com/paranext/paranext-core/tree/main/lib/platform-bible-react"
    click LibUtils "https://github.com/paranext/paranext-core/tree/main/lib/platform-bible-utils"

    %% Styles
    classDef main fill:#cce5ff,stroke:#0366d6,color:#000
    classDef renderer fill:#cbeeff,stroke:#007acc,color:#000
    classDef extension fill:#d4f5d4,stroke:#28a745,color:#000
    classDef dotnet fill:#ffe5b4,stroke:#d97706,color:#000
    classDef node fill:#e2e2e2,stroke:#6c757d,color:#000
    classDef shared fill:#fff5b1,stroke:#d4a017,color:#000
```
