# inkandswitch/potluck architecture

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

- Interactive diagram: https://gitdiagram.com/inkandswitch/potluck
- Repository: https://github.com/inkandswitch/potluck

## Overview

##### Project type and purpose
- This is a front-end-only, single-page application research prototype (“Potluck”) built with React, TypeScript, Vite, and Tailwind CSS.
- Its goal is to let users turn plain text documents into “live” interactive tools: run searches over text, author formulas, and display dynamic annotations in the document.

##### File structure
- Top-level:
- index.html: main app shell
- embedded.html/embedded-test.html: stripped-down shells for embedding the editor in other pages
- package.json, tsconfig.json, vite.config.ts, tailwind.config.js: toolchain / build config
- src/: all source code—React components, utility modules, data, assets, and a small “refactor” script folder.
- src/main.tsx: app entry point
- src/App.tsx + components (Editor.tsx, DocumentSidebar.tsx, HighlightHoverCard.tsx, etc.) form the UI layer
- src/compute.ts, src/formulas.tsx, src/highlight.ts, src/markdown.ts, src/patterns.ts: core logic for query, computation, and text processing
- src/persistence.tsx: layer handling document state saving/loading
- src/data + sample-data/: static JSON, CSV, and text fixtures for demos
- No backend folder: it’s a static web app, everything runs in the browser.

##### README for additional insights
- Emphasizes “gradual enrichment from docs to apps”
- Features: live searches, formulas, dynamic annotations
- Research prototype, not a production service

##### Detail
- Sequence: user event → UI component → computation → UI update → persistence

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Infrastructure"
        direction TB
        SAS["Static Asset Server"]:::infra
        VL["Bundler/Loader (Vite)"]:::infra
    end

    subgraph "Browser (Client)"
        direction TB

        subgraph "UI Layer (React + Tailwind CSS)"
            direction TB
            App["App.tsx"]:::ui
            Sidebar["DocumentSidebar.tsx"]:::ui
            Editor["Editor.tsx"]:::ui
            EmbeddedDoc["EmbeddedDocument.tsx"]:::ui
            HoverCard["HighlightHoverCard.tsx"]:::ui
            NumberSlider["NumberSliderComponent.tsx"]:::ui
            Nutrition["NutritionLabel.tsx"]:::ui
            SheetCal["SheetCalendar.tsx"]:::ui
            SheetComp["SheetComponent.tsx"]:::ui
            Timer["TimerComponent.tsx"]:::ui
        end

        subgraph "Core Logic Modules"
            direction TB
            Markdown["markdown.ts"]:::core
            Highlight["highlight.ts"]:::core
            Patterns["patterns.ts"]:::core
            Compute["compute.ts"]:::core
            Formulas["formulas.tsx"]:::core
        end

        Persistence(("LocalStorage / File System API")):::db

        subgraph "Data Layer"
            direction TB
            SD["sample-data/"]:::db
            DataDir["src/data/"]:::db
        end

        Utils["utils.ts / primitives.ts"]:::util
    end

    %% Connections
    VL -->|"builds assets"| SAS
    SAS -->|"fetch index.html, embedded.html, embedded-test.html, JS bundle"| Browser

    Browser -->|"initialize (main.tsx)"| App
    App --> Sidebar
    App --> Editor
    App --> EmbeddedDoc

    Editor -->|"run query"| Compute
    Compute -->|"compute formulas"| Formulas
    Editor -->|"parse text"| Markdown
    Editor --> Patterns
    Patterns --> Highlight
    Highlight --> HoverCard
    Formulas --> Nutrition
    Formulas --> NumberSlider
    Formulas --> SheetCal
    Formulas --> SheetComp
    Formulas --> Timer

    UIEvent["User Event"] --> Editor
    Editor -->|"render UI"| App

    App -->|"save changes"| Persistence
    Persistence -->|"load document"| Editor
    SD --> Persistence
    DataDir --> Persistence

    Utils --> Markdown
    Utils --> Patterns
    Utils --> Highlight
    Utils --> Compute
    Utils --> Formulas

    %% Click Events
    click SAS "https://github.com/inkandswitch/potluck/blob/main/index.html"
    click SAS "https://github.com/inkandswitch/potluck/blob/main/embedded.html"
    click SAS "https://github.com/inkandswitch/potluck/blob/main/embedded-test.html"
    click VL "https://github.com/inkandswitch/potluck/blob/main/vite.config.ts"
    click VL "https://github.com/inkandswitch/potluck/blob/main/tsconfig.json"
    click VL "https://github.com/inkandswitch/potluck/blob/main/postcss.config.js"
    click VL "https://github.com/inkandswitch/potluck/blob/main/tailwind.config.js"
    click VL "https://github.com/inkandswitch/potluck/blob/main/package.json"
    click App "https://github.com/inkandswitch/potluck/blob/main/src/App.tsx"
    click Sidebar "https://github.com/inkandswitch/potluck/blob/main/src/DocumentSidebar.tsx"
    click Editor "https://github.com/inkandswitch/potluck/blob/main/src/Editor.tsx"
    click EmbeddedDoc "https://github.com/inkandswitch/potluck/blob/main/src/EmbeddedDocument.tsx"
    click HoverCard "https://github.com/inkandswitch/potluck/blob/main/src/HighlightHoverCard.tsx"
    click NumberSlider "https://github.com/inkandswitch/potluck/blob/main/src/NumberSliderComponent.tsx"
    click Nutrition "https://github.com/inkandswitch/potluck/blob/main/src/NutritionLabel.tsx"
    click SheetCal "https://github.com/inkandswitch/potluck/blob/main/src/SheetCalendar.tsx"
    click SheetComp "https://github.com/inkandswitch/potluck/blob/main/src/SheetComponent.tsx"
    click Timer "https://github.com/inkandswitch/potluck/blob/main/src/TimerComponent.tsx"
    click Markdown "https://github.com/inkandswitch/potluck/blob/main/src/markdown.ts"
    click Highlight "https://github.com/inkandswitch/potluck/blob/main/src/highlight.ts"
    click Patterns "https://github.com/inkandswitch/potluck/blob/main/src/patterns.ts"
    click Compute "https://github.com/inkandswitch/potluck/blob/main/src/compute.ts"
    click Formulas "https://github.com/inkandswitch/potluck/blob/main/src/formulas.tsx"
    click Persistence "https://github.com/inkandswitch/potluck/blob/main/src/persistence.tsx"
    click SD "https://github.com/inkandswitch/potluck/tree/main/sample-data/"
    click DataDir "https://github.com/inkandswitch/potluck/tree/main/src/data/"
    click Utils "https://github.com/inkandswitch/potluck/blob/main/src/utils.ts"
    click Utils "https://github.com/inkandswitch/potluck/blob/main/src/primitives.ts"

    %% Styles
    classDef infra fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef client fill:#ffffff,stroke:#888888
    classDef ui fill:#FFD8A8,stroke:#cc5500,color:#cc5500
    classDef core fill:#D0FFD6,stroke:#228B22,color:#228B22
    classDef db fill:#E0E0E0,stroke:#666666,color:#333333
    classDef util fill:#F0F0F0,stroke:#999999,color:#555555
```
