# potahtml/pota architecture

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

- Interactive diagram: https://gitdiagram.com/potahtml/pota
- Repository: https://github.com/potahtml/pota

## Overview

##### Project type and purpose
- pota is an open-source, compiler-less Reactive Web Renderer library for building UI with HTML/XML or JSX.
- It provides:
- A Babel preset (transform-time) that converts JSX into highly optimized partial DOM-expression calls.
- A runtime core that handles reactivity (signals, stores), scheduling, and DOM rendering.
- A set of built-in components (Router, Show, For, etc.) and a plugin system for common patterns (useTimeout, useScroll, etc.).

##### File structure
Top-level directories show distinct architectural layers:
- src/babel-preset → the build-time pipeline (JSX → partials)
- src/core → the runtime engine (renderer, scheduler, XML handling)
- src/lib → the reactive primitives (SignalEmitter, store, reconcile, tracker)
- src/components → the declarative UI components (Router, Portal, Switch, etc.)
- src/plugin → an extensible plugin API (clipboard, fullscreen, useLocation, etc.)
- src/jsx → the `jsx-runtime` for JSX-style import aliases
- src/exports.js & package.json → packaging and public API surface

##### README for insights
- Confirms no separate backend, purely a UI library.
- Emphasizes inspiration from SolidJS but with custom preferences.
- Notes documentation site, templates, and Babel-only transformation.

##### Components
a. Main Components
1. Developer Code (JS/TS + optional JSX)
2. Babel Preset Pipeline
3. Pota Library (layered modules)
- Runtime Core (renderer, scheduler, xml)
- Reactivity Layer (SignalEmitter, store, reconcile, tracker)
- Component Layer (Collapse, For, Router, etc.)
- Plugin Layer (useTimeout, useScroll, etc.)
- JSX Runtime (jsx-runtime.js)
4. Browser DOM / XML host environment

b. Relationships & Interactions
- Developer code → passes through Babel Preset → emits optimized JS partial calls.
- Transformed code imports Pota’s Runtime Core & Reactivity modules.
- At runtime, Reactive Primitives notify the Scheduler → Core Renderer updates the DOM.
- Components and Plugins sit atop Core & Reactivity; they import and invoke core APIs.

c. Architectural Patterns & Principles
- Layered modular architecture: transformation layer, runtime engine, reactive primitives, UI components, plugins.
- Plugin architecture: easy extension without touching core.
- Compiler-less approach: build-time transforms only where needed, minimal coupling to build tools.
- Inspired by MVC in that “View” (components) is separate from “Model” (reactive store), orchestrated by the scheduler.

d. Key Technologies & Frameworks
- Babel (custom preset, rollup config for bundling)
- JavaScript/TypeScript types (`pota.d.ts`, `tsconfig.json`)
- Rollup for packaging (rollup.config.js)
- Node/NPM packaging (package.json, .npmignore)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer Source (JSX/TSX)"]:::dev
    Developer --> BabelPreset

    subgraph "Babel Preset Pipeline"
        BabelPreset["Babel Preset Pipeline"]:::transform
        BPIndex["index.js"]:::transform
        BPRollup["rollup.config.js"]:::transform
        BPTransform["transform/*.js"]:::transform
    end
    click BPIndex "https://github.com/potahtml/pota/blob/master/src/babel-preset/index.js"
    click BPRollup "https://github.com/potahtml/pota/blob/master/src/babel-preset/rollup.config.js"
    click BPTransform "https://github.com/potahtml/pota/tree/master/src/babel-preset/transform/"

    BabelPreset --> Transformed["Transformed Output (JS Partial Calls)"]:::transform
    Transformed --> RuntimeCore
    Transformed --> Reactivity
    Transformed --> JSXRuntime

    subgraph "Runtime Core"
        RuntimeCore["Runtime Core"]:::core
        Renderer["renderer.js"]:::core
        Scheduler["scheduler.js"]:::core
        XML["xml.js"]:::core
        PropsMain["props/@main.js"]:::core
        PropsOther["props/*.js"]:::core
    end
    click Renderer "https://github.com/potahtml/pota/blob/master/src/core/renderer.js"
    click Scheduler "https://github.com/potahtml/pota/blob/master/src/core/scheduler.js"
    click XML "https://github.com/potahtml/pota/blob/master/src/core/xml.js"
    click PropsMain "https://github.com/potahtml/pota/blob/master/src/core/props/@main.js"
    click PropsOther "https://github.com/potahtml/pota/tree/master/src/core/props/"

    subgraph "Reactivity Layer"
        Reactivity["Reactivity Layer"]:::react
        SignalEmitter["SignalEmitter.js"]:::react
        ReactiveJS["reactive.js"]:::react
        Store["store.js"]:::react
        StoreDir["store/"]:::react
    end
    click SignalEmitter "https://github.com/potahtml/pota/blob/master/src/lib/classes/SignalEmitter.js"
    click ReactiveJS "https://github.com/potahtml/pota/blob/master/src/lib/reactive.js"
    click Store "https://github.com/potahtml/pota/blob/master/src/lib/store.js"
    click StoreDir "https://github.com/potahtml/pota/tree/master/src/lib/store/"

    subgraph "Component Layer"
        Components["Component Layer"]:::ext
        ComponentsMain["@main.js"]:::ext
        Collapse["Collapse.js"]:::ext
        CustomElement["CustomElement.js"]:::ext
        Dynamic["Dynamic.js"]:::ext
        ForComp["For.js"]:::ext
        Head["Head.js"]:::ext
        Portal["Portal.js"]:::ext
        RangeComp["Range.js"]:::ext
        RouterComp["Router.js"]:::ext
        ShowComp["Show.js"]:::ext
        SwitchComp["Switch.js"]:::ext
        RouterDir["router/"]:::ext
    end
    click ComponentsMain "https://github.com/potahtml/pota/blob/master/src/components/@main.js"
    click Collapse "https://github.com/potahtml/pota/blob/master/src/components/Collapse.js"
    click CustomElement "https://github.com/potahtml/pota/blob/master/src/components/CustomElement.js"
    click Dynamic "https://github.com/potahtml/pota/blob/master/src/components/Dynamic.js"
    click ForComp "https://github.com/potahtml/pota/blob/master/src/components/For.js"
    click Head "https://github.com/potahtml/pota/blob/master/src/components/Head.js"
    click Portal "https://github.com/potahtml/pota/blob/master/src/components/Portal.js"
    click RangeComp "https://github.com/potahtml/pota/blob/master/src/components/Range.js"
    click RouterComp "https://github.com/potahtml/pota/blob/master/src/components/Router.js"
    click ShowComp "https://github.com/potahtml/pota/blob/master/src/components/Show.js"
    click SwitchComp "https://github.com/potahtml/pota/blob/master/src/components/Switch.js"
    click RouterDir "https://github.com/potahtml/pota/tree/master/src/components/router/"

    subgraph "Plugin Layer"
        Plugins["Plugin Layer"]:::ext
        Bind["bind.js"]:::ext
        ClickOutside["clickoutside.js"]:::ext
        Clipboard["clipboard.js"]:::ext
        Fullscreen["fullscreen.js"]:::ext
        UsePlugins["use*.js"]:::ext
    end
    click Bind "https://github.com/potahtml/pota/blob/master/src/plugin/bind.js"
    click ClickOutside "https://github.com/potahtml/pota/blob/master/src/plugin/clickoutside.js"
    click Clipboard "https://github.com/potahtml/pota/blob/master/src/plugin/clipboard.js"
    click Fullscreen "https://github.com/potahtml/pota/blob/master/src/plugin/fullscreen.js"
    click UsePlugins "https://github.com/potahtml/pota/tree/master/src/plugin/"

    subgraph "JSX Runtime"
        JSXRuntime["JSX Runtime"]:::ext
        JSXRuntimeFile["jsx-runtime.js"]:::ext
        JSXDT["jsx.d.ts"]:::ext
    end
    click JSXRuntimeFile "https://github.com/potahtml/pota/blob/master/src/jsx/jsx-runtime.js"
    click JSXDT "https://github.com/potahtml/pota/blob/master/src/jsx/jsx.d.ts"

    subgraph "Public API & Packaging"
        PublicAPI["Public API & Packaging"]:::ext
        Exports["exports.js"]:::ext
        PackageJSON["package.json"]:::ext
        DTS["pota.d.ts"]:::ext
    end
    click Exports "https://github.com/potahtml/pota/blob/master/src/exports.js"
    click PackageJSON "https://github.com/potahtml/pota/blob/master/package.json"
    click DTS "https://github.com/potahtml/pota/blob/master/pota.d.ts"

    RuntimeCore --> Browser["Browser DOM / XML Host"]:::host
    Reactivity --> RuntimeCore
    Components --> RuntimeCore
    Components --> Reactivity
    Plugins --> RuntimeCore
    Plugins --> Reactivity

    classDef transform fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef react fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef ext fill:#FFDEAD,stroke:#333,stroke-width:1px
    classDef host fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef dev fill:#B0E0E6,stroke:#333,stroke-width:1px
```
