# mentat-is/gulpui-web architecture

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

- Interactive diagram: https://gitdiagram.com/mentat-is/gulpui-web
- Repository: https://github.com/mentat-is/gulpui-web

## Overview

1. **What this repo is**
   - This is a **React-based browser client** for the Gulp backend.
   - The application is centered on **authentication, operation/session selection, and a workspace for inspecting and manipulating Gulp data**.
   - The backend is the system-of-record; this client is primarily a **rich UI, orchestration, and visualization layer**.

2. **Top-level runtime boundary**
   - The entry point is a standard SPA bootstrap (`src/index.tsx`) that mounts the app into `public/index.html`.
   - The main application is built from React components, with global concerns split into context providers for **application state, theme, boundary/detached rendering, and extension integration**.
   - The repo also contains a dedicated `Auth.page.tsx` and a `RendererTest.page.tsx`, indicating separate entry views for login and renderer validation.

3. **Backend communication layer**
   - The client talks to Gulp through `src/class/API.tsx` and `src/class/SmartSocket.tsx`.
   - Authentication uses the user-provided **server URL, username, and password** from the login screen, then transitions into **operation/session management**.
   - `src/dto/*` and `src/class/Engine.dto.tsx` define the serialized contract between client and backend, while `src/lib/WindowBridge.ts` suggests cross-window or host-bridge messaging when the UI is embedded or detached.

4. **Session and operation flow**
   - The README describes the core workflow: **login → choose or create operation → select or resume session**.
   - This is reflected in domain entities like `Operation`, `Session`-related messaging, `Source`, `Request`, `Query`, and `User`.
   - The client persists enough state to support **returning to unfinished work**, while the backend remains authoritative for operations and server-side data.

5. **Domain model and local state**
   - `src/entities/*` holds the application’s core domain objects: **apps, operations, sources, filters, links, groups, notes, queries, requests, highlights, and mappings**.
   - `src/store/DataStore.ts` and `src/class/IndexedDB.ts` indicate a local persistence/cache layer, likely used for **offline-ish state retention, workspace continuity, and performance-sensitive data**.
   - This is a clear boundary: **backend data and session metadata flow in**, while client-side stores retain UI and interaction state.

6. **Main workspace and visualization layer**
   - The main interactive workspace lives under `src/app/body/*`, especially `Canvas.tsx`, `Navigator.tsx`, and `Timeline.tsx`.
   - These components imply a **multi-pane analysis surface** where the user can navigate, inspect timeline/history, and work on a canvas-based view.
   - `src/class/RenderEngine.tsx`, `Default.engine.tsx`, `Graph.engine.tsx`, and `Height.engine.tsx` suggest pluggable rendering modes for different visualizations of the same underlying data.

7. **Rendering and overlay mechanics**
   - The `RenderEngine` and `Ruler.drawer.tsx` act as the low-level drawing subsystem for the canvas/graph UI.
   - `src/overlays/Highlights.tsx` and the magnifier-related DTO/hooks indicate layered visual aids on top of the core render surface.
   - This is an important diagram boundary: **domain objects are rendered by engines onto a canvas-like surface, with overlays for selection, highlighting, and inspection**.

8. **Worker-based data processing**
   - Heavy or asynchronous processing is offloaded to `src/workers/Data.worker.ts`, `src/workers/Ingest.worker.ts`, and `src/workers/IngestWorker.manager.ts`.
   - That separation means ingestion and data transformation are intentionally kept **out of the main UI thread**.
   - In architecture terms, the flow is: **user action or backend input → worker processing → normalized data/state → renderer/UI**.

9. **Plugin and extensibility model**
   - The repo has a dedicated plugin area (`src/plugins/coconut.tsx` plus its JSON descriptor), along with plugin-oriented UI such as `AdvancedPluginParams`.
   - `src/entities/addon/*`, `src/context/Extension.context.tsx`, and mapping-related panels show that plugins can contribute **parameters, mapping rules, and extension behavior**.
   - This is a meaningful subsystem: the client is not just fixed UI; it supports **extension-driven workflows** and possibly paid add-ons (reinforced by the `copy_paid_plugins.js` script).

10. **Feature-oriented UI windows and dialogs**
   - The app uses many focused components for distinct workspace tasks: **query builder, table view, history, notes, collaboration list, AI assistant window, custom parameters, and pointer/highlight tools**.
   - `src/dialogs/*`, `src/components/FloatingWindow.tsx`, `src/ui/Dialog.tsx`, and related UI primitives suggest a **windowed, multi-panel interaction model** rather than a single-page form flow.
   - These windows are built on top of a shared UI component library under `src/ui/*`.

11. **Guided workflows and onboarding banners**
   - The `src/banners/*` directory contains a large set of feature banners: upload, select files, filter file, queries, permissions, preview, session, settings, and more.
   - These banners appear to be a **workflow guidance layer** that explains or gates features as the user progresses through the analysis process.
   - For a diagram, think of them as **contextual onboarding/feature affordances** attached to the workspace, not core business logic.

12. **Styling, theming, and presentation boundaries**
   - The repo uses CSS modules heavily, plus a separate theme system in `src/themes/*`.
   - `Theme.context.tsx` and theme CSS files indicate that visual appearance is **switchable and centrally managed**, while individual components remain style-scoped.
   - `src/ui/icons.ts`, `src/font`, and `src/global.css` support a consistent design system across the app.

13. **Deployment and operational tooling**
   - The repo is containerized (`Dockerfile`, `docker-compose.yml`) and has GitHub CI/release workflows.
   - Scripts handle version stamping and packaging, which matters if the architecture diagram includes deployment or release flow.
   - There is also a `public/version` asset, implying the UI can display build/version metadata at runtime.

14. **How to draw the main data flow**
   - The simplest accurate flow is:
     **user → auth page → backend API/socket → operation/session state → local store/IndexedDB + workers → render engines/UI windows → overlays/dialogs/banners**.
   - The main boundaries are:
     **browser UI vs Gulp backend**, **main thread vs web workers**, and **shared domain model vs presentation components**.

Main entry points: [`src/store/DataStore.ts`](https://github.com/mentat-is/gulpui-web/blob/master/src/store/DataStore.ts) (Data store), [`src/index.tsx`](https://github.com/mentat-is/gulpui-web/blob/master/src/index.tsx) (App bootstrap), [`src/class/API.tsx`](https://github.com/mentat-is/gulpui-web/blob/master/src/class/API.tsx) (API client), [`src/app/body/Canvas.tsx`](https://github.com/mentat-is/gulpui-web/blob/master/src/app/body/Canvas.tsx) (Canvas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime Shell"]
  node_index(("App bootstrap<br/>SPA entry<br/>[index.tsx]"))
  node_app_context["App state<br/>React context"]
  node_theme_context["Theme<br/>React context<br/>[Theme.context.tsx]"]
  node_boundary_context["Boundary<br/>React context"]
  node_auth_page["Login page<br/>auth view<br/>[Auth.page.tsx]"]
  node_renderer_test["Renderer test<br/>test view"]
end

subgraph group_backend["Backend & State"]
  node_api["API client<br/>backend API<br/>[API.tsx]"]
  node_socket["Socket<br/>realtime transport<br/>[SmartSocket.tsx]"]
  node_contracts["DTOs<br/>data contract<br/>[index.tsx]"]
  node_enginedto["Engine DTOs<br/>render contract<br/>[Engine.dto.tsx]"]
  node_datastore[("Data store<br/>local state<br/>[DataStore.ts]")]
  node_indexeddb[("IndexedDB<br/>local storage<br/>[IndexedDB.ts]")]
  node_windowbridge["Window bridge<br/>host bridge<br/>[WindowBridge.ts]"]
end

subgraph group_workspace["Workspace UI"]
  node_canvas["Canvas<br/>workspace surface<br/>[Canvas.tsx]"]
  node_navigator["Navigator<br/>workspace pane<br/>[Navigator.tsx]"]
  node_timeline["Timeline<br/>workspace pane<br/>[Timeline.tsx]"]
  node_dialogs["Dialogs<br/>modal layer<br/>[Event.dialog.tsx]"]
  node_overlays["Overlays<br/>visual overlay<br/>[Highlights.tsx]"]
end

subgraph group_rendering["Rendering Pipeline"]
  node_renderengines["Render engines<br/>renderer set<br/>[Default.engine.tsx]"]
  node_ruler["Ruler<br/>draw helper<br/>[Ruler.drawer.tsx]"]
end

subgraph group_extensibility["Extensibility"]
  node_plugins["Plugins<br/>extension module<br/>[coconut.tsx]"]
  node_extension_context["Extensions<br/>React context"]
  node_mapping_params["Mapping params<br/>plugin ui"]
end

subgraph group_shared["Shared UI"]
  node_ui_kit["UI kit<br/>shared components<br/>[Dialog.tsx]"]
  node_banners["Guidance banners<br/>workflow banners<br/>[Index.banner.tsx]"]
  node_themes["Themes<br/>style system<br/>[index.ts]"]
end

node_index -->|"wraps"| node_app_context
node_index -->|"uses"| node_theme_context
node_index -->|"wraps"| node_boundary_context
node_index -->|"routes to"| node_auth_page
node_index -->|"routes to"| node_renderer_test
node_auth_page -->|"authenticates via"| node_api
node_api -->|"opens"| node_socket
node_api -->|"serializes"| node_contracts
node_api -->|"serializes"| node_enginedto
node_socket -->|"syncs"| node_datastore
node_datastore -->|"persists"| node_indexeddb
node_datastore -->|"drives"| node_canvas
node_datastore -->|"drives"| node_navigator
node_datastore -->|"drives"| node_timeline
node_windowbridge -->|"connects"| node_boundary_context
node_canvas -->|"renders with"| node_renderengines
node_renderengines -->|"draws with"| node_ruler
node_renderengines -->|"composes"| node_overlays
node_dialogs -->|"built on"| node_ui_kit
node_banners -->|"built on"| node_ui_kit
node_plugins -->|"registers with"| node_extension_context
node_extension_context -->|"exposes"| node_mapping_params
node_mapping_params -->|"reads/writes"| node_datastore
node_theme_context -->|"selects"| node_themes
node_app_context -->|"coordinates"| node_datastore
node_app_context -->|"calls"| node_api
node_canvas -->|"opens"| node_dialogs
node_canvas -->|"guides"| node_banners

click node_index "https://github.com/mentat-is/gulpui-web/blob/master/src/index.tsx"
click node_app_context "https://github.com/mentat-is/gulpui-web/blob/master/src/context/Application.context.tsx"
click node_theme_context "https://github.com/mentat-is/gulpui-web/blob/master/src/context/Theme.context.tsx"
click node_boundary_context "https://github.com/mentat-is/gulpui-web/blob/master/src/context/Boundary.context.tsx"
click node_auth_page "https://github.com/mentat-is/gulpui-web/blob/master/src/page/Auth.page.tsx"
click node_renderer_test "https://github.com/mentat-is/gulpui-web/blob/master/src/page/RendererTest.page.tsx"
click node_api "https://github.com/mentat-is/gulpui-web/blob/master/src/class/API.tsx"
click node_socket "https://github.com/mentat-is/gulpui-web/blob/master/src/class/SmartSocket.tsx"
click node_contracts "https://github.com/mentat-is/gulpui-web/blob/master/src/dto/index.tsx"
click node_enginedto "https://github.com/mentat-is/gulpui-web/blob/master/src/class/Engine.dto.tsx"
click node_datastore "https://github.com/mentat-is/gulpui-web/blob/master/src/store/DataStore.ts"
click node_indexeddb "https://github.com/mentat-is/gulpui-web/blob/master/src/class/IndexedDB.ts"
click node_windowbridge "https://github.com/mentat-is/gulpui-web/blob/master/src/lib/WindowBridge.ts"
click node_canvas "https://github.com/mentat-is/gulpui-web/blob/master/src/app/body/Canvas.tsx"
click node_navigator "https://github.com/mentat-is/gulpui-web/blob/master/src/app/body/Navigator.tsx"
click node_timeline "https://github.com/mentat-is/gulpui-web/blob/master/src/app/body/Timeline.tsx"
click node_dialogs "https://github.com/mentat-is/gulpui-web/blob/master/src/dialogs/Event.dialog.tsx"
click node_overlays "https://github.com/mentat-is/gulpui-web/blob/master/src/overlays/Highlights.tsx"
click node_renderengines "https://github.com/mentat-is/gulpui-web/blob/master/src/engines/Default.engine.tsx"
click node_ruler "https://github.com/mentat-is/gulpui-web/blob/master/src/class/Ruler.drawer.tsx"
click node_plugins "https://github.com/mentat-is/gulpui-web/blob/master/src/plugins/coconut.tsx"
click node_extension_context "https://github.com/mentat-is/gulpui-web/blob/master/src/context/Extension.context.tsx"
click node_mapping_params "https://github.com/mentat-is/gulpui-web/blob/master/src/components/AdvancedPluginParams.tsx"
click node_ui_kit "https://github.com/mentat-is/gulpui-web/blob/master/src/ui/Dialog.tsx"
click node_banners "https://github.com/mentat-is/gulpui-web/blob/master/src/banners/Index.banner.tsx"
click node_themes "https://github.com/mentat-is/gulpui-web/blob/master/src/themes/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_app_context,node_theme_context,node_boundary_context,node_auth_page,node_renderer_test toneBlue
class node_api,node_socket,node_contracts,node_enginedto,node_datastore,node_indexeddb,node_windowbridge toneAmber
class node_canvas,node_navigator,node_timeline,node_dialogs,node_overlays toneMint
class node_renderengines,node_ruler toneRose
class node_plugins,node_extension_context,node_mapping_params toneIndigo
class node_ui_kit,node_banners,node_themes toneTeal
```

## Components

### Runtime Shell

SPA entry points, app providers, and alternate pages.

- [App bootstrap](https://github.com/mentat-is/gulpui-web/blob/master/src/index.tsx): SPA entry · Mounts the React application into the browser shell. · `src/index.tsx`
- [App state](https://github.com/mentat-is/gulpui-web/blob/master/src/context/Application.context.tsx): React context · Global application state and cross-cutting providers. · `src/context/Application.context.tsx`
- [Theme](https://github.com/mentat-is/gulpui-web/blob/master/src/context/Theme.context.tsx): React context · Central theme selection and styling coordination. · `src/context/Theme.context.tsx`
- [Boundary](https://github.com/mentat-is/gulpui-web/blob/master/src/context/Boundary.context.tsx): React context · Detached/boundary rendering and host integration boundary. · `src/context/Boundary.context.tsx`
- [Login page](https://github.com/mentat-is/gulpui-web/blob/master/src/page/Auth.page.tsx): auth view · Dedicated authentication flow for server URL and credentials. · `src/page/Auth.page.tsx`
- [Renderer test](https://github.com/mentat-is/gulpui-web/blob/master/src/page/RendererTest.page.tsx): test view · Standalone page for validating the rendering layer. · `src/page/RendererTest.page.tsx`

### Backend & State

API transport, persistence, and session-backed domain state.

- [API client](https://github.com/mentat-is/gulpui-web/blob/master/src/class/API.tsx): backend API · Primary HTTP/control channel to the Gulp backend. · `src/class/API.tsx`
- [Socket](https://github.com/mentat-is/gulpui-web/blob/master/src/class/SmartSocket.tsx): realtime transport · Bidirectional session and event transport. · `src/class/SmartSocket.tsx`
- [DTOs](https://github.com/mentat-is/gulpui-web/blob/master/src/dto/index.tsx): data contract · Serialized client-backend message and payload schemas. · `src/dto/index.tsx`
- [Engine DTOs](https://github.com/mentat-is/gulpui-web/blob/master/src/class/Engine.dto.tsx): render contract · Shared rendering and engine payload definitions. · `src/class/Engine.dto.tsx`
- [Data store](https://github.com/mentat-is/gulpui-web/blob/master/src/store/DataStore.ts): local state · Client-side cache and workspace persistence layer. · `src/store/DataStore.ts`
- [IndexedDB](https://github.com/mentat-is/gulpui-web/blob/master/src/class/IndexedDB.ts): local storage · Browser persistence backing the local workspace state. · `src/class/IndexedDB.ts`
- [Window bridge](https://github.com/mentat-is/gulpui-web/blob/master/src/lib/WindowBridge.ts): host bridge · Cross-window or embedded-host communication bridge. · `src/lib/WindowBridge.ts`

### Workspace UI

Main analysis surface, panes, dialogs, and overlays.

- [Canvas](https://github.com/mentat-is/gulpui-web/blob/master/src/app/body/Canvas.tsx): workspace surface · Main analysis canvas and interactive composition surface. · `src/app/body/Canvas.tsx`
- [Navigator](https://github.com/mentat-is/gulpui-web/blob/master/src/app/body/Navigator.tsx): workspace pane · Navigation and exploration pane for workspace entities. · `src/app/body/Navigator.tsx`
- [Timeline](https://github.com/mentat-is/gulpui-web/blob/master/src/app/body/Timeline.tsx): workspace pane · History and session chronology surface. · `src/app/body/Timeline.tsx`
- [Dialogs](https://github.com/mentat-is/gulpui-web/blob/master/src/dialogs/Event.dialog.tsx): modal layer · Focused dialogs for groups, events, and hints. · `src/dialogs/Event.dialog.tsx`
- [Overlays](https://github.com/mentat-is/gulpui-web/blob/master/src/overlays/Highlights.tsx): visual overlay · Highlight and inspection overlays rendered above the workspace. · `src/overlays/Highlights.tsx`

### Rendering Pipeline

Canvas rendering engines and drawing helpers.

- [Render engines](https://github.com/mentat-is/gulpui-web/blob/master/src/engines/Default.engine.tsx): renderer set · Pluggable rendering modes for different visualizations. · `src/engines/Default.engine.tsx`
- [Ruler](https://github.com/mentat-is/gulpui-web/blob/master/src/class/Ruler.drawer.tsx): draw helper · Low-level drawing helper for layout and measurement. · `src/class/Ruler.drawer.tsx`

### Extensibility

Plugins, extension context, and mapping-oriented add-ons.

- [Plugins](https://github.com/mentat-is/gulpui-web/blob/master/src/plugins/coconut.tsx): extension module · Plugin entrypoint and packaged plugin descriptor. · `src/plugins/coconut.tsx`
- [Extensions](https://github.com/mentat-is/gulpui-web/blob/master/src/context/Extension.context.tsx): React context · Runtime extension integration and plugin coordination. · `src/context/Extension.context.tsx`
- [Mapping params](https://github.com/mentat-is/gulpui-web/blob/master/src/components/AdvancedPluginParams.tsx): plugin ui · Advanced plugin parameter and mapping configuration UI. · `src/components/AdvancedPluginParams.tsx`

### Shared UI

Reusable UI kit, themes, and banners used across the app.

- [UI kit](https://github.com/mentat-is/gulpui-web/blob/master/src/ui/Dialog.tsx): shared components · Reusable dialogs, windows, controls, and layout primitives. · `src/ui/Dialog.tsx`
- [Guidance banners](https://github.com/mentat-is/gulpui-web/blob/master/src/banners/Index.banner.tsx): workflow banners · Contextual onboarding and feature-affordance banners. · `src/banners/Index.banner.tsx`
- [Themes](https://github.com/mentat-is/gulpui-web/blob/master/src/themes/index.ts): style system · Centralized theme palette and visual variants. · `src/themes/index.ts`

## Connections

- App bootstrap → App state: wraps · Bootstraps the app through global providers.
- App bootstrap → Theme: uses · Initializes the active visual theme.
- App bootstrap → Boundary: wraps · Enables detached and embedded rendering modes.
- App bootstrap → Login page: routes to · Starts at authentication when not signed in.
- App bootstrap → Renderer test: routes to · Supports a dedicated renderer validation entry.
- Login page → API client: authenticates via · Submits server URL and credentials to backend.
- API client → Socket: opens · Uses socket transport for live session control.
- API client → DTOs: serializes · Uses shared DTOs for backend messages.
- API client → Engine DTOs: serializes · Shares render-engine contract structures.
- Socket → Data store: syncs · Feeds session and workspace updates into local state.
- Data store → IndexedDB: persists · Stores retained workspace and session data locally.
- Data store → Canvas: drives · Provides normalized data for the main workspace.
- Data store → Navigator: drives · Feeds navigation and selection state.
- Data store → Timeline: drives · Feeds history and session chronology.
- Window bridge → Boundary: connects · Bridges the app shell and external host contexts.
- Canvas → Render engines: renders with · Delegates visual modes to pluggable engines.
- Render engines → Ruler: draws with · Uses low-level drawing helpers and measurement.
- Render engines → Overlays: composes · Stacks selection and highlight overlays above rendering.
- Dialogs → UI kit: built on · Uses shared modal and control primitives.
- Guidance banners → UI kit: built on · Uses the common component library for guidance UI.
- Plugins → Extensions: registers with · Integrates plugin behavior into the app runtime.
- Extensions → Mapping params: exposes · Provides extension-specific parameter and mapping UI.
- Mapping params → Data store: reads/writes · Stores mapping choices and last-used configurations.
- Theme → Themes: selects · Switches among centrally managed theme variants.
- App state → Data store: coordinates · Coordinates application state around the local store.
- App state → API client: calls · Triggers backend operations from UI state.
- Canvas → Dialogs: opens · Launches contextual dialogs for selected entities.
- Canvas → Guidance banners: guides · Shows workflow guidance around analysis tasks.
