# emzzy241/unfinished architecture

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

- Interactive diagram: https://gitdiagram.com/emzzy241/unfinished
- Repository: https://github.com/emzzy241/unfinished

## Overview

##### Project type and purpose
- This is a client-side JavaScript library for building web applications (like React), named “unfinished.”
- It provides:
- A JSX runtime (to convert JSX into function calls)
- A core UI library (reactive components, control-flow helpers, utilities)
- A built-in router (single-page app navigation)
- Shadow DOM and teleport support
- Hot-module-reload support and a small footprint

##### File structure
- Top-level directories and files:
- source/ – all library source code
- scripts/ – build and development-server scripts
- docs/ – documentation site content
- package.json, bun.lockb, deno.json, tsconfig.json – configuration for packaging, bundling, TypeScript, runtime, etc.
- .github/workflows/pkg.pr.yml – CI workflow for publishing
- Inside source/:
- jsx-runtime/ – code that implements JSX-to-call conversion at runtime
- library/ – core exports: for.js, if.js, switch.js, observer.js, jsx.js, utils.js
- render/ – rendering logic that mounts virtual nodes to the DOM
- router/ – SPA router (routeTree, lazy loading, middleware)
- shadowroot/ – helper to mount inside a shadow DOM
- teleport/ – portal/teleport support

##### README for additional insights
- Key Features list confirms the above breakdown
- Mentions underlying reactivity library (@adbl/cells) for automatic updates

a. Main components:
- Developer’s application code (the end-user app written in JSX)
- Build & bundler toolchain (scripts/build.js, bun or Deno, package.json)
- Library runtime modules:
– JSX Runtime
– Core helpers & reactivity (library/)
– Renderer (render/)
– Router (router/)
– ShadowDOM (shadowroot/)
– Teleport (teleport/)
- External dependencies (npm, @adbl/cells)
- Browser (DOM)
b. Relationships & interactions:
1. Developer code (JSX) → bundled by build tool → includes calls into the JSX Runtime
2. JSX Runtime → creates virtual element descriptions → passed to Renderer
3. Renderer → mounts/upates real DOM nodes
4. Core helpers (for, if, switch, observer) wrap data and UI for reactivity
5. Router intercepts navigation events → updates Renderer with the correct view
6. Shadowroot & Teleport modules let components mount into isolated DOM subtrees or external containers
7. Hot Module Reload: file changes → development server (scripts/start) → swaps updated modules in the browser without full reload
c. Architectural patterns & design principles:
- Modular design: each feature lives in its own directory under source/
- Single responsibility: JSX handling separate from rendering, routing, reactivity
- Unopinionated DOM integration: components ARE DOM nodes (no virtual-DOM diff engine)
- Pluggable SPA routing with middleware and lazy loading
d. Relevant technologies/frameworks:
- bun (bun.lockb) and/or Deno for building/serving
- @adbl/cells for reactivity
- NPM scripts for package management
- GitHub Actions (CI) for publication

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Application
    DevApp["Developer App (JSX)"]:::app

    %% Build & Bundler
    subgraph "Build & Bundler"
        Build["Build Script"]:::buildtools
        DevServer["Dev Server (HMR)"]:::buildtools
        DevServerConfig["Dev Server Config"]:::buildtools
        DevServerLock["Dev Server Lock"]:::buildtools
    end

    %% Library Modules
    subgraph "Library Modules"
        JSXRuntime["JSX Runtime"]:::runtime
        CoreLib["Core UI Library"]:::runtime
        For["for helper"]:::runtime
        If["if helper"]:::runtime
        Switch["switch helper"]:::runtime
        Observer["observer"]:::runtime
        JSXHelper["jsx exports"]:::runtime
        Utils["utils"]:::runtime
        Renderer["Renderer"]:::runtime
        Router["Router"]:::runtime
        Lazy["Lazy Loading"]:::runtime
        Middleware["Middleware API"]:::runtime
        RouteTree["Route Tree Builder"]:::runtime
        Shadow["Shadow DOM Support"]:::runtime
        Teleport["Teleport Support"]:::runtime
    end

    %% Browser/DOM
    Browser["Browser / DOM"]:::browser

    %% External Dependencies
    subgraph "External Dependencies"
        NPM["npm registry"]:::external
        Cells["@adbl/cells"]:::external
    end

    %% Documentation & CI
    Docs["Documentation"]:::docs
    CI["CI/CD Workflow"]:::ci

    %% Development-time flows
    DevApp -->|"JSX Code"| Build
    Build -->|"bundle includes"| JSXRuntime
    Build -->|"bundle includes"| CoreLib
    Build -->|"bundle includes"| Renderer
    Build -->|"bundle includes"| Router
    Build -->|"bundle includes"| Shadow
    Build -->|"bundle includes"| Teleport
    DevApp -->|"file change"| DevServer
    DevServer -->|"swap modules"| Browser

    %% Runtime flows
    JSXRuntime -->|"VNode"| Renderer
    CoreLib -->|"reactivity hooks"| Renderer
    Router -->|"route change"| Renderer
    Shadow -->|"mount in Shadow DOM"| Renderer
    Teleport -->|"portal mount"| Renderer
    Renderer -->|"DOM updates"| Browser

    %% External dependencies usage
    NPM --> Build
    Cells --> CoreLib
    CI --> NPM

    %% Click Events
    click JSXRuntime "https://github.com/emzzy241/unfinished/blob/main/source/jsx-runtime/index.js"
    click CoreLib "https://github.com/emzzy241/unfinished/blob/main/source/library/index.js"
    click For "https://github.com/emzzy241/unfinished/blob/main/source/library/for.js"
    click If "https://github.com/emzzy241/unfinished/blob/main/source/library/if.js"
    click Switch "https://github.com/emzzy241/unfinished/blob/main/source/library/switch.js"
    click Observer "https://github.com/emzzy241/unfinished/blob/main/source/library/observer.js"
    click JSXHelper "https://github.com/emzzy241/unfinished/blob/main/source/library/jsx.js"
    click Utils "https://github.com/emzzy241/unfinished/blob/main/source/library/utils.js"
    click Renderer "https://github.com/emzzy241/unfinished/blob/main/source/render/index.js"
    click Router "https://github.com/emzzy241/unfinished/blob/main/source/router/index.js"
    click Lazy "https://github.com/emzzy241/unfinished/blob/main/source/router/lazy.js"
    click Middleware "https://github.com/emzzy241/unfinished/blob/main/source/router/middleware.js"
    click RouteTree "https://github.com/emzzy241/unfinished/blob/main/source/router/routeTree.js"
    click Shadow "https://github.com/emzzy241/unfinished/blob/main/source/shadowroot/index.js"
    click Teleport "https://github.com/emzzy241/unfinished/blob/main/source/teleport/index.js"
    click Build "https://github.com/emzzy241/unfinished/blob/main/scripts/build.js"
    click DevServer "https://github.com/emzzy241/unfinished/blob/main/scripts/start/index.js"
    click DevServerConfig "https://github.com/emzzy241/unfinished/blob/main/scripts/start/package.json"
    click DevServerLock "https://github.com/emzzy241/unfinished/blob/main/scripts/start/bun.lockb"
    click Docs "https://github.com/emzzy241/unfinished/blob/main/docs/README.md"
    click CI "https://github.com/emzzy241/unfinished/blob/main/.github/workflows/pkg.pr.yml"
    click PkgManifest "https://github.com/emzzy241/unfinished/blob/main/package.json"
    click BunLock "https://github.com/emzzy241/unfinished/blob/main/bun.lockb"
    click DenoConfig "https://github.com/emzzy241/unfinished/blob/main/deno.json"
    click TSConfig "https://github.com/emzzy241/unfinished/blob/main/tsconfig.json"

    %% Styles
    classDef app fill:#fff8dc,stroke:#000
    classDef buildtools fill:#ffa500,stroke:#000
    classDef runtime fill:#add8e6,stroke:#000
    classDef external fill:#d3d3d3,stroke:#000
    classDef browser fill:#98fb98,stroke:#000
    classDef docs fill:#dda0dd,stroke:#000
    classDef ci fill:#d3d3d3,stroke:#000
```
