How mentat-is/gulpui-web works
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: DataStore.ts Data store · index.tsx App bootstrap · API.tsx API client · Canvas.tsx Canvas
Components 26
Runtime Shell
SPA entry points, app providers, and alternate pages.
- App bootstrap · Mounts the React application into the browser shell.
src/index.tsx - App state · Global application state and cross-cutting providers.
src/context/Application.context.tsx - Theme · Central theme selection and styling coordination.
src/context/Theme.context.tsx - Boundary · Detached/boundary rendering and host integration boundary.
src/context/Boundary.context.tsx - Login page · Dedicated authentication flow for server URL and credentials.
src/page/Auth.page.tsx - Renderer test · Standalone page for validating the rendering layer.
src/page/RendererTest.page.tsx
Backend & State
API transport, persistence, and session-backed domain state.
- API client · Primary HTTP/control channel to the Gulp backend.
src/class/API.tsx - Socket · Bidirectional session and event transport.
src/class/SmartSocket.tsx - DTOs · Serialized client-backend message and payload schemas.
src/dto/index.tsx - Engine DTOs · Shared rendering and engine payload definitions.
src/class/Engine.dto.tsx - Data store · Client-side cache and workspace persistence layer.
src/store/DataStore.ts - IndexedDB · Browser persistence backing the local workspace state.
src/class/IndexedDB.ts - Window bridge · Cross-window or embedded-host communication bridge.
src/lib/WindowBridge.ts
Workspace UI
Main analysis surface, panes, dialogs, and overlays.
- Canvas · Main analysis canvas and interactive composition surface.
src/app/body/Canvas.tsx - Navigator · Navigation and exploration pane for workspace entities.
src/app/body/Navigator.tsx - Timeline · History and session chronology surface.
src/app/body/Timeline.tsx - Dialogs · Focused dialogs for groups, events, and hints.
src/dialogs/Event.dialog.tsx - Overlays · Highlight and inspection overlays rendered above the workspace.
src/overlays/Highlights.tsx
Rendering Pipeline
Canvas rendering engines and drawing helpers.
- Render engines · Pluggable rendering modes for different visualizations.
src/engines/Default.engine.tsx - Ruler · Low-level drawing helper for layout and measurement.
src/class/Ruler.drawer.tsx
Extensibility
Plugins, extension context, and mapping-oriented add-ons.
- Plugins · Plugin entrypoint and packaged plugin descriptor.
src/plugins/coconut.tsx - Extensions · Runtime extension integration and plugin coordination.
src/context/Extension.context.tsx - Mapping params · 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 · Reusable dialogs, windows, controls, and layout primitives.
src/ui/Dialog.tsx - Guidance banners · Contextual onboarding and feature-affordance banners.
src/banners/Index.banner.tsx - Themes · Centralized theme palette and visual variants.
src/themes/index.ts
Connections 28
- 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.