# spaansba/foresightjs architecture

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

- Interactive diagram: https://gitdiagram.com/spaansba/foresightjs
- Repository: https://github.com/spaansba/foresightjs

## Overview

##### Project type and purpose
- This is a monorepo for a client-side JavaScript library (js.foresight) plus companion tooling:
- Core library (packages/js.foresight) – a framework-agnostic user-intent predictor.
- DevTools extension (packages/js.foresight-devtools) – visual debugging overlay built with Lit.
- Playground/demo app (packages/devpage) – a React/Vite app showcasing features.
- Documentation site (packages/docs) – a Docusaurus-driven doc portal.
- Purpose: ship a light, zero-config prediction library + tooling + docs + demo in one workspace.

##### File structure
- Top-level workspace files: pnpm-workspace.yaml, tsconfig.base.json, scripts/list-packages.js
- packages/js.foresight
- src/core, managers, predictors, helpers, types – implements the prediction engine
- build scripts: tsup.config.ts, vitest.config.mjs
- packages/js.foresight-devtools
- A standalone devtools package with Lit web components (control panel, overlay)
- Integrates via “foresight events” emitted by the core library
- packages/devpage
- React + Vite app demonstrating the useForesight hook
- src/components, hooks, stores show UI integration points
- packages/docs
- Docusaurus config, markdown docs, React components for the docs site
- No backend or database – all client-side.

##### README for additional insights
- Core concepts: ForesightManager, prediction strategies (mouse, scroll, keyboard, touch)
- Integration points: import library, initialize manager, register elements
- DevTools: listens for events, overlays debug UI
- Playground: React integration via useForesight hook

##### Final advice
- Be detailed: show each package as a grouped component
- Essential layers: build → publish → install → runtime
- Don’t overthink: separate into logical modules & show their interactions
- Review the file tree and README to ensure no key submodule is missing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development & Build Environment
    subgraph "Development/Build Environment"
        direction TB
        WS1["pnpm-workspace.yaml"]:::gray
        WS2["tsconfig.base.json"]:::gray
        WS3["scripts/list-packages.js"]:::gray
    end

    %% Packages
    subgraph "Packages (Monorepo)"
        direction TB

        subgraph "Core Library (js.foresight)"
            direction TB
            FFM["ForesightManager"]:::blue
            DH["DesktopHandler"]:::blue
            TH["TouchDeviceHandler"]:::blue
            BFM["BaseForesightModule"]:::blue
            subgraph "Predictors"
                direction TB
                MP(("MousePredictor")):::green
                SP(("ScrollPredictor")):::green
                TP(("TabPredictor")):::green
                TSP(("TouchStartPredictor")):::green
                VP(("ViewportPredictor")):::green
            end
            CB["tsup.config.ts"]:::gray
        end

        subgraph "DevTools (js.foresight-devtools)"
            direction TB
            DTE["src/index.ts"]:::blue
            CP(("control-panel.ts")):::orange
            DO(("debug-overlay.ts")):::orange
            DB["tsup.config.ts"]:::gray
        end

        subgraph "Demo App (devpage)"
            direction TB
            DA["src/App.tsx"]:::blue
            UF["useForesight.ts"]:::blue
            DV["vite.config.ts"]:::gray
        end

        subgraph "Docs Site (docs)"
            direction TB
            DC["docusaurus.config.ts"]:::gray
        end
    end

    %% CI/CD & Publish
    subgraph "CI/CD & Publish"
        direction TB
        Lister["list-packages.js"]:::gray
        Pipeline["Build & Publish Pipeline"]:::gray
        NPM["npm Registry"]:::gray
    end

    %% Browser Runtime
    subgraph "Browser Runtime"
        direction TB
        DOM["Browser DOM Events"]:::gray
        CoreRun["js.foresight Runtime"]:::blue
        EventBus["Event Bus"]:::blue
        DevToolsUI["DevTools UI"]:::orange
        DemoUI["Demo App UI"]:::blue
    end

    %% Relationships
    DOM -->|"register elements"| FFM
    FFM -->|uses| DH
    FFM -->|uses| TH
    DH -->|tracks| MP
    DH -->|tracks| SP
    DH -->|tracks| TP
    TH -->|tracks| TSP
    TH -->|tracks| VP
    MP -->|predicts| BFM
    SP -->|predicts| BFM
    TP -->|predicts| BFM
    TSP -->|predicts| BFM
    VP -->|predicts| BFM
    BFM -->|emit events| EventBus
    EventBus -->|subscribe| DevToolsUI
    EventBus -->|callbacks| DemoUI

    DA -->|calls| FFM
    UF -->|wraps| FFM

    WS3 -->|lists| Lister
    Lister --> Pipeline
    CB --> Pipeline
    DB --> Pipeline
    DV --> Pipeline
    Pipeline --> NPM

    %% Click Events
    click FFM "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/managers/ForesightManager.ts"
    click DH "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/managers/DesktopHandler.ts"
    click TH "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/managers/TouchDeviceHandler.ts"
    click BFM "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/core/BaseForesightModule.ts"
    click MP "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/predictors/MousePredictor.ts"
    click SP "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/predictors/ScrollPredictor.ts"
    click TP "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/predictors/TabPredictor.ts"
    click TSP "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/predictors/TouchStartPredictor.ts"
    click VP "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/src/predictors/ViewportPredictor.ts"
    click CB "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight/tsup.config.ts"
    click DTE "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight-devtools/src/index.ts"
    click CP "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight-devtools/src/lit-entry/control-panel/control-panel.ts"
    click DO "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight-devtools/src/lit-entry/debug-overlay/debug-overlay.ts"
    click DB "https://github.com/spaansba/foresightjs/blob/main/packages/js.foresight-devtools/tsup.config.ts"
    click DA "https://github.com/spaansba/foresightjs/blob/main/packages/devpage/src/App.tsx"
    click UF "https://github.com/spaansba/foresightjs/blob/main/packages/devpage/src/hooks/useForesight.ts"
    click DV "https://github.com/spaansba/foresightjs/blob/main/packages/devpage/vite.config.ts"
    click DC "https://github.com/spaansba/foresightjs/blob/main/packages/docs/docusaurus.config.ts"
    click WS3 "https://github.com/spaansba/foresightjs/blob/main/scripts/list-packages.js"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef green fill:#DFFFD0,stroke:#2e8b57,color:#2e8b57,stroke-width:1px;
    classDef orange fill:#FFE4B5,stroke:#d2691e,color:#d2691e,stroke-width:1px;
    classDef gray fill:#F0F0F0,stroke:#A0A0A0,color:#606060,stroke-width:1px;
```
