# geodacenter/openassistant architecture

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

- Interactive diagram: https://gitdiagram.com/geodacenter/openassistant
- Repository: https://github.com/geodacenter/openassistant

## Overview

##### Project type and purpose
- This is a large monorepo JavaScript/TypeScript library called “OpenAssistant.”
- Purpose: provide a core LLM-assistant engine, a suite of “tools” (Plot, Geo, Map, DuckDB, GeoDa, OSM, etc.), reusable React UI components (chat interface, visualization containers), shared utilities, plus examples/playground/docs for developers to build AI data-analysis applications.

##### File structure
- Top-level configuration: lerna.json, turbo.json, GitHub workflows, esbuild.config.mjs, TypeScript and ESLint configs.
- packages/
- core – the assistant engine: tool invocation, LLM abstractions, streaming, hooks.
- tools/* – domain-specific tool plugins (duckdb, geoda, map, osm, plots). Each exports a tool interface, registerTools, uses WASM or external APIs.
- components/* – headless React components for charts, maps, tables.
- ui – pre-built chat UI component using the core engine and components.
- utils – shared helpers (caching, formatting, tool-output management).
- examples/ & playground/ & storybook/ – client applications demonstrating usage.
- website/ – Docusaurus-based docs site and blog.
- CI/CD & scripts/ – build, test, versioning, publish pipelines.

##### README for insights
- Describes core features: one interface for multiple LLM providers, tool ecosystem, React chat component.
- Shows flow: user prompt → tool selection → context.getValues → tool executes (e.g. DuckDB, ECharts, Mapbox, OSM) → returns data and UI metadata → callback on completion → UI renders result.
- Highlights dependency injection, plugin architecture, and examples path.

##### Essential architectural elements
- Monorepo management at a high level, not every script.
- Runtime flow (user → UI → core → tools → external → back).
- Every major package boundary is represented and labelled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Applications & Documentation"
        Clients["Examples / Playground / Storybook / Docs"]:::clients
    end

    User["User"]:::clients

    subgraph "Chat UI Layer"
        ChatUI["@openassistant/ui (Chat UI)"]:::ui
    end

    subgraph "Core Engine"
        Core["@openassistant/core (Assistant Core)"]:::core
    end

    subgraph "Tool Plugins"
        Tools["@openassistant/tools/*"]:::tools
    end

    subgraph "External Services & Engines"
        External["LLM Providers / WASM modules / APIs"]:::external
    end

    subgraph "Headless Components"
        Components["@openassistant/components/*"]:::components
    end

    subgraph "Utilities"
        Utils["@openassistant/utils"]:::utils
    end

    subgraph "Monorepo Orchestration & CI/CD"
        CICD["Lerna/TurboRepo / GitHub Actions / esbuild"]:::cicd
    end

    User -->|"interacts with"| ChatUI
    ChatUI -->|"createAssistant/processMessage"| Core
    Core -->|"invokeTool"| Tools
    Tools -->|"execute (WASM/API)"| External
    External -->|"return data"| Tools
    Tools -->|"streamResult"| Core
    Core -->|"streamResult"| ChatUI
    ChatUI -->|"render results"| Components
    Utils -.supports.-> Core
    Utils -.supports.-> ChatUI
    CICD -->|"build & publish"| ChatUI
    CICD -->|"build & publish"| Core
    CICD -->|"build & publish"| Tools
    CICD -->|"build & publish"| Components
    CICD -->|"build & publish"| Utils
    Clients -->|"uses packages"| ChatUI
    Clients -->|"uses packages"| Core

    %% Click Events
    click CICD "https://github.com/geodacenter/openassistant/blob/main/lerna.json"
    click CICD "https://github.com/geodacenter/openassistant/blob/main/turbo.json"
    click CICD "https://github.com/geodacenter/openassistant/blob/main/.github/workflows/build_publish.yml"
    click CICD "https://github.com/geodacenter/openassistant/blob/main/esbuild.config.mjs"

    click Core "https://github.com/geodacenter/openassistant/blob/main/packages/core/esbuild.config.mjs"
    click Core "https://github.com/geodacenter/openassistant/blob/main/packages/core/src/index.ts"
    click Core "https://github.com/geodacenter/openassistant/blob/main/packages/core/src/hooks/use-assistant.ts"
    click Core "https://github.com/geodacenter/openassistant/blob/main/packages/core/src/lib/chat-handler.ts"
    click Core "https://github.com/geodacenter/openassistant/blob/main/packages/core/src/utils/create-assistant.ts"
    click Core "https://github.com/geodacenter/openassistant/blob/main/packages/core/src/llm/openai.ts"

    click Tools "https://github.com/geodacenter/openassistant/blob/main/packages/tools/duckdb/src/register-tools.ts"
    click Tools "https://github.com/geodacenter/openassistant/blob/main/packages/tools/geoda/src/register-tools.ts"
    click Tools "https://github.com/geodacenter/openassistant/blob/main/packages/tools/map/src/register-tools.ts"
    click Tools "https://github.com/geodacenter/openassistant/blob/main/packages/tools/osm/src/register-tools.ts"
    click Tools "https://github.com/geodacenter/openassistant/blob/main/packages/tools/plots/src/register-tools.ts"
    click External "https://github.com/geodacenter/openassistant/blob/main/packages/core/src/llm/openai.ts"
    click External "https://github.com/geodacenter/openassistant/blob/main/packages/tools/duckdb/src/query.ts"
    click External "https://github.com/geodacenter/openassistant/blob/main/packages/tools/geoda/src/global-moran/tool.ts"
    click External "https://github.com/geodacenter/openassistant/blob/main/packages/tools/map/src/leaflet/tool.ts"
    click External "https://github.com/geodacenter/openassistant/blob/main/packages/tools/osm/src/geocoding.ts"

    click Components "https://github.com/geodacenter/openassistant/blob/main/packages/components/common/src/index.ts"
    click Components "https://github.com/geodacenter/openassistant/blob/main/packages/components/echarts/src/index.ts"
    click Components "https://github.com/geodacenter/openassistant/blob/main/packages/components/hooks/src/index.ts"
    click Components "https://github.com/geodacenter/openassistant/blob/main/packages/components/keplergl/src/index.ts"
    click Components "https://github.com/geodacenter/openassistant/blob/main/packages/components/leaflet/src/index.ts"
    click Components "https://github.com/geodacenter/openassistant/blob/main/packages/components/tables/src/index.ts"
    click Components "https://github.com/geodacenter/openassistant/blob/main/packages/components/vegalite/src/index.ts"

    click ChatUI "https://github.com/geodacenter/openassistant/blob/main/packages/ui/esbuild.config.mjs"
    click ChatUI "https://github.com/geodacenter/openassistant/blob/main/packages/ui/src/components/assistant.tsx"
    click ChatUI "https://github.com/geodacenter/openassistant/blob/main/packages/ui/src/components/message-card.tsx"
    click ChatUI "https://github.com/geodacenter/openassistant/blob/main/packages/ui/src/components/prompt-input.tsx"
    click ChatUI "https://github.com/geodacenter/openassistant/blob/main/packages/ui/src/containers/echarts-skeleton.tsx"

    click Utils "https://github.com/geodacenter/openassistant/blob/main/packages/utils/esbuild.config.mjs"
    click Utils "https://github.com/geodacenter/openassistant/blob/main/packages/utils/src/cache.ts"
    click Utils "https://github.com/geodacenter/openassistant/blob/main/packages/utils/src/format.ts"
    click Utils "https://github.com/geodacenter/openassistant/blob/main/packages/utils/src/tool-output-manager.ts"
    click Utils "https://github.com/geodacenter/openassistant/blob/main/packages/utils/src/version.ts"

    click Clients "https://github.com/geodacenter/openassistant/tree/main/examples/"
    click Clients "https://github.com/geodacenter/openassistant/blob/main/playground/app/page.tsx"
    click Clients "https://github.com/geodacenter/openassistant/blob/main/storybook/.storybook/main.ts"
    click Clients "https://github.com/geodacenter/openassistant/tree/main/website/"

    classDef core fill:#cce5ff,stroke:#3399ff,color:#003366
    classDef tools fill:#d4edda,stroke:#28a745,color:#155724
    classDef ui fill:#e2e3f3,stroke:#6f42c1,color:#38137e
    classDef utils fill:#f8f9fa,stroke:#6c757d,color:#343a40
    classDef clients fill:#fff3cd,stroke:#d39e00,color:#856404
    classDef external fill:#f8d7da,stroke:#dc3545,color:#721c24
    classDef components fill:#ffeeba,stroke:#ffc107,color:#856404
    classDef cicd fill:#e2e3e5,stroke:#adb5bd,color:#495057
```
