# michelle123lam/lloom architecture

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

- Interactive diagram: https://gitdiagram.com/michelle123lam/lloom
- Repository: https://github.com/michelle123lam/lloom

## Overview

##### Project Type and Purpose
- LLooM is a hybrid full-stack research prototype comprising:
- A Python package (“text_lloom”) implementing the core concept-induction algorithm that orchestrates calls to OpenAI GPT-4o/mini and processes unstructured text.
- A static web application (“LLooM Workbench”) built with Vite, Svelte components, and VitePress for documentation and interactive visualization.
- Purpose: enable analysts to run concept induction on text datasets (via the Python library) and explore the results in an interactive browser UI.

##### Top-Level File Structure and Architectural Indicators
- “text_lloom/” directory: the algorithmic backend (Python library modules for concept induction, LLM prompts, openai integration, workbench API).
- “src/” directory: the front-end application code in Svelte (components for tables, charts, matrix view, overview histogram).
- “docs/.vitepress/”: documentation site configuration and theming.
- “docs/public/data/”: precomputed JSON/CSV datasets for demos.
- “.github/workflows/deploy.yml”: CI/CD pipeline deploying the static site to GitHub Pages.
- Config files: “requirements.txt” (Python deps), “package.json” (JS deps), “vite.config.js” / “vite.config-select.js” (build targets for different UI modes).

##### Key Components
A. Algorithm Backend (Python “text_lloom” package)
– Modules: concept induction, concept application, LLM wrapper, prompt definitions, workbench API.
– External Service: OpenAI API (GPT-4o/GPT-4o-mini).
– Data Inputs: raw unstructured text (CSV/JSON), user-authored custom concept definitions.
– Data Outputs: structured concept definitions + match results (JSON).

B. Workbench Front-end (Static Web App)
– Build System: Vite + Svelte, served as static assets.
– Components: ConceptOverview, MatrixView, DetailView, Tables, Charts.
– Data Fetch: loads JSON/CSV from “docs/public/data/” or user-provided API endpoint.
– User Interactions: filter by slices, annotate custom concepts, inspect examples.

C. Documentation & Demo Site
– VitePress site assembling markdown pages, custom Vue components for demos.
– Static assets: demo datasets, media, notebooks.
– CI/CD: GitHub Actions builds & deploys to GitHub Pages.

D. External Integrations
– GitHub Pages: hosts static site and front-end.
– PyPI Registry: hosts the “text_lloom” package for pip install.
– Colab Notebooks: for end-user walkthroughs (links in docs).

##### Relationships and Data Flows
1. User supplies dataset → calls Python API (locally or in Colab).
2. Python package samples text spans → sends prompts to OpenAI → receives concept candidates.
3. Python refines, scores, and applies concepts back to the dataset → exports JSON results.
4. Front-end loads JSON results via HTTP fetch (static or custom endpoint).
5. Svelte components render visualizations (overview, matrix, detail).
6. User may author new concepts in UI → optional round-trip back to Python API for re-induction (if enabled).
7. CI/CD pipeline triggers on Git push → builds docs & front-end → deploys to GitHub Pages.

##### Architectural Patterns and Principles
- Separation of concerns: algorithmic layer decoupled from visualization layer.
- Client-server decoupling: front-end is a static asset consumer, backend is a library or microservice.
- Static site generation for docs and demos; dynamic algorithm hosted in user environment.
- Data-driven visualizations: JSON schemas as the contract between backend and front-end.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawText["Raw Text Input (CSV/JSON)"]:::data
        UserDefs["User-Authored Concept Definitions"]:::data
        JSONOutput["Concept JSON Output"]:::data
    end

    %% Algorithm Layer
    subgraph "Algorithm Layer"
        direction TB
        CI["concept_induction.py"]:::backend
        click CI "https://github.com/michelle123lam/lloom/blob/main/text_lloom/src/text_lloom/concept_induction.py"
        CA["concept.py"]:::backend
        click CA "https://github.com/michelle123lam/lloom/blob/main/text_lloom/src/text_lloom/concept.py"
        LW["llm.py"]:::backend
        click LW "https://github.com/michelle123lam/lloom/blob/main/text_lloom/src/text_lloom/llm.py"
        OA["llm_openai.py"]:::backend
        click OA "https://github.com/michelle123lam/lloom/blob/main/text_lloom/src/text_lloom/llm_openai.py"
        PD["prompts.py"]:::backend
        click PD "https://github.com/michelle123lam/lloom/blob/main/text_lloom/src/text_lloom/prompts.py"
        API["workbench.py"]:::backend
        click API "https://github.com/michelle123lam/lloom/blob/main/text_lloom/src/text_lloom/workbench.py"
        OpenAI["OpenAI API (GPT-4o/mini)"]:::external
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        subgraph "Static Web App"
            direction TB
            EntryStd["index.js"]:::frontend
            click EntryStd "https://github.com/michelle123lam/lloom/blob/main/src/index.js"
            EntrySel["index_select.js"]:::frontend
            click EntrySel "https://github.com/michelle123lam/lloom/blob/main/src/index_select.js"
            OH["OverviewHistogram.svelte"]:::frontend
            click OH "https://github.com/michelle123lam/lloom/blob/main/src/components/OverviewHistogram.svelte"
            MV["MatrixView.svelte"]:::frontend
            click MV "https://github.com/michelle123lam/lloom/blob/main/src/components/MatrixView.svelte"
            MI["MatrixInner.svelte"]:::frontend
            click MI "https://github.com/michelle123lam/lloom/blob/main/src/components/MatrixInner.svelte"
            CSC["ConceptSummaryChart.svelte"]:::frontend
            click CSC "https://github.com/michelle123lam/lloom/blob/main/src/components/ConceptSummaryChart.svelte"
            GSC["GroupSummaryChart.svelte"]:::frontend
            click GSC "https://github.com/michelle123lam/lloom/blob/main/src/components/GroupSummaryChart.svelte"
            CT["ConceptTable.svelte"]:::frontend
            click CT "https://github.com/michelle123lam/lloom/blob/main/src/components/ConceptTable.svelte"
            CDV["ConceptView.svelte"]:::frontend
            click CDV "https://github.com/michelle123lam/lloom/blob/main/src/components/ConceptView.svelte"
            CSV["ConceptSelectView.svelte"]:::frontend
            click CSV "https://github.com/michelle123lam/lloom/blob/main/src/components/ConceptSelectView.svelte"
            GDV["GroupView.svelte"]:::frontend
            click GDV "https://github.com/michelle123lam/lloom/blob/main/src/components/GroupView.svelte"
        end
        subgraph "Documentation & Demo Site"
            direction TB
            VPConfig["docs/.vitepress/config.js"]:::frontend
            click VPConfig "https://github.com/michelle123lam/lloom/blob/main/docs/.vitepress/config.js"
            ThemeComp1["ConceptHist.vue"]:::frontend
            click ThemeComp1 "https://github.com/michelle123lam/lloom/blob/main/docs/.vitepress/theme/ConceptHist.vue"
            ThemeComp2["DemoConcepts.vue"]:::frontend
            click ThemeComp2 "https://github.com/michelle123lam/lloom/blob/main/docs/.vitepress/theme/DemoConcepts.vue"
            ThemeComp3["DemoLayout.vue"]:::frontend
            click ThemeComp3 "https://github.com/michelle123lam/lloom/blob/main/docs/.vitepress/theme/DemoLayout.vue"
            ThemeIndex["theme index.js"]:::frontend
            click ThemeIndex "https://github.com/michelle123lam/lloom/blob/main/docs/.vitepress/theme/index.js"
            MDPages["Markdown Pages"]:::frontend
            click MDPages "https://github.com/michelle123lam/lloom/blob/main/docs/about/,docs/api/,docs/examples/,docs/index.md"
            DemoData["Demo Data Assets"]:::data
            click DemoData "https://github.com/michelle123lam/lloom/tree/main/docs/public/data/"
            Notebooks["Walkthrough Notebooks"]:::data
            click Notebooks "https://github.com/michelle123lam/lloom/tree/main/docs/public/nb/"
            Media["Media Assets"]:::data
            click Media "https://github.com/michelle123lam/lloom/tree/main/docs/public/media/"
        end
    end

    %% Deployment Layer
    subgraph "Deployment Layer"
        direction TB
        CIYML["deploy.yml"]:::external
        click CIYML "https://github.com/michelle123lam/lloom/blob/main/.github/workflows/deploy.yml"
        GitHubPages["GitHub Pages"]:::external
        PyPI["PyPI Registry"]:::external
    end

    %% Flows
    RawText -->|reads| CI
    UserDefs -->|inputs| CI
    CI -->|uses prompts| PD
    CI -->|calls| OA
    OA -->|requests| OpenAI
    OpenAI -->|response| LW
    LW -->|generates| CA
    CA -->|applies| API
    API -->|exports| JSONOutput
    JSONOutput -->|HTTP fetch| EntryStd
    JSONOutput -->|HTTP fetch| EntrySel
    EntryStd -->|renders| OH
    EntryStd -->|renders| MV
    MV -->|uses| MI
    EntryStd -->|renders| CSC
    EntryStd -->|renders| GSC
    EntryStd -->|renders| CT
    EntryStd -->|renders| CDV
    EntrySel -->|renders| CSV
    EntrySel -->|renders| GDV

    CIYML -->|builds & deploys| GitHubPages
    EntryStd -->|deployed to| GitHubPages
    EntrySel -->|deployed to| GitHubPages
    VPConfig -->|site deployed to| GitHubPages

    CI -->|published| PyPI

    %% Styles
    classDef backend fill:#cce5ff,stroke:#004085,color:#004085
    classDef frontend fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
