# liz-origin/elizabeth architecture

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

- Interactive diagram: https://gitdiagram.com/liz-origin/elizabeth
- Repository: https://github.com/liz-origin/elizabeth

## Overview

This repo is a **web framework + compiler/transpiler + dev server + client runtime** built on **Bun**. It introduces a custom component syntax (`.liz` in examples; README mentions `.eliz` but tree shows `.liz`) that transpiles to JS/TS with `f()` calls, supports **SSR**, and implements **Islands Architecture** (partial hydration) with a small **client runtime** (`useState`, event handling).

- **Toolchain pipeline** (CLI → transpile → bundle/run dev server)
- **Runtime architecture** (server SSR → HTML + island markers/scripts → browser hydration per-island)
- **Key modules** (transpiler, router, server, core render, client runtime)
- **Example apps** (as consumers) and generated cache artifacts (`.elizabeth/cache/*.tsx`)

##### File structure: what’s architecturally meaningful
Top-level:
- `src/` = framework implementation
- `bin/elizabeth` = CLI entrypoint wrapper
- `examples/*` = consumer projects demonstrating usage
- `bun.lock`, `package.json`, `tsconfig.json` = Bun/TS build + runtime configuration

Within `src/`:
- `src/cli.ts` — CLI behavior (dev/build/etc. as implied)
- `src/transpile.ts` — **the compiler/transpiler**: `.liz` → JS/TS/TSX using `f()`
- `src/core.ts` — core `f()` + `render()` (SSR output, island script injection likely happens here or adjacent)
- `src/framework/server.ts` — dev server (Bun HTTP + file watching)
- `src/framework/router.ts` — file-based routing (maps `app/**/index.liz` to URLs)
- `src/framework/client.ts` — browser runtime (hydration + `useState`)
- `src/index.tsx` / `src/framework/*` / `src/index.tsx` — public API surface + exports

Examples indicate ecosystem integration:
- `examples/liz-tw/` includes `tailwind.config.js`, `build-tailwind.ts` → external build step feeding CSS into the app.

The README explicitly defines the pipeline:
##### `useState` state management within islands

- **Build/Dev pipeline (tooling)**: CLI + transpiler + dev server + cache output
- **Runtime (request/response + hydration)**: server SSR + browser hydration

##### Core Runtime – Server (`src/core.ts` render + `f()`)

**Browser-side**
##### Client Runtime (`src/framework/client.ts`) (hydration + hooks like `useState`)
7. **Islands Loader / Hydration Scripts** (conceptual component: “per-island bundles / inline scripts”)

**Artifacts / Inputs**
##### Transpile Cache (`.elizabeth/cache/*.tsx`) (derived output)
10. (Optional) **Tailwind Build Step** (for `examples/liz-tw`: `build-tailwind.ts` → CSS output)

You want at least these directional flows:

**Dev/build time**
- `Developer` → `CLI (bun run dev / elizabeth)`
- `CLI` → `Dev Server`
- `Dev Server` ↔ `Router` (resolve URL ↔ file path)
- `Dev Server` → `Transpiler` (compile `.liz` when requested or on change)
- `Transpiler` → `.elizabeth/cache/*.tsx` (write derived TSX/TS modules)
- `Dev Server` → `Core render()` (SSR renders compiled components)

**Request-time (server)**
- `Browser HTTP GET /route` → `Dev Server`
- `Dev Server` → `Router` → identifies `app/.../index.liz`
- `Dev Server` → `Transpiler` (ensure compiled module available)
- `Dev Server` → `Core render(vdom)` → returns:
- **Static HTML**
- **Island markers / island manifest**
- **Hydration script references** (per island)

**Client-time (browser)**
- `Browser` receives HTML → displays static content immediately
- `Browser` loads `Client Runtime` + per-island scripts
- `Client Runtime` hydrates only detected islands
- `useState` works inside hydrated islands (no hydration = no state)

**Styling flows**
- `.css` and `*.module.css` imported by `.liz`:
- As inputs to transpilation/build
- Tailwind (example): `build-tailwind.ts` → generated CSS → linked in HTML

##### Architectural patterns explicitly
Callouts/labels for:
- **Islands Architecture / Partial Hydration**
- **File-based routing** (`app/about/index.liz` → `/about`)
- **Compiler/transpiler stage** (custom syntax → JS/TSX with `f()`)
- **SSR first** (HTML returned from `render()`)
- **Client runtime minimalism** (only islands hydrate)

##### Technologies (don’t overdo, but be explicit)
- **Bun runtime** on server/tooling side
- **TypeScript** (src is TS; generated cache is TSX)
- **Browser** side runtime
- **Tailwind** only as an optional external pipeline in the example(s)
- **CSS Modules** support path (module import → hashed class mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========= Global actors/environments (vertical orientation) =========
    Dev["Developer"]:::actor
    Bun["Bun Runtime (Tooling + SSR)"]:::boundary
    Browser["Browser (Client Runtime)"]:::boundary

    Dev -->|"runs elizabeth dev/build"| CLIWrap["CLI Entrypoint"]:::tool
    CLIWrap -->|"invokes"| CLILogic["CLI Commands (dev/build)"]:::tool

    %% ========= Bun-side / Framework internals =========
    subgraph BunLayer["Server/Tooling Layer (Bun)"]
        direction TB

        APISurface["Public API Surface (exports)"]:::server

        subgraph Framework["Framework (src/framework/*)"]
            direction TB
            DevServer["Dev Server (HTTP + file watch)"]:::server
            Router["File-based Router"]:::server
            ClientRuntime["Client Runtime (hydration + useState)"]:::client
        end

        subgraph Compiler["Compiler/Renderer (src/*)"]
            direction TB
            Transpiler["Transpiler/Compiler (.liz -> TS/TSX with f())"]:::compiler
            CoreSSR["Core SSR Runtime (f() + render())"]:::server

            IslandDetect["Island Detection (event handlers)"]:::server
            IslandScripts["Hydration Script Generation (per-island)"]:::server
        end
    end

    Bun -->|"hosts/runs"| DevServer
    CLILogic -->|"starts"| DevServer
    CLILogic -->|"uses"| Transpiler

    DevServer -->|"imports/exports"| APISurface
    DevServer -->|"SSR calls"| CoreSSR

    CoreSSR -->|"detects"| IslandDetect
    IslandDetect -->|"drives"| IslandScripts

    %% ========= App sources (examples as consumers) =========
    subgraph Apps["Consumer Apps (examples/*)"]
        direction TB

        AppBasic["Basic App (.liz + CSS)"]:::app
        AppElizabeth["Routing/Layout App (.liz + CSS Modules)"]:::app
        AppLizTw["Tailwind Example App"]:::app

        LizIndex["app/index.liz"]:::doc
        AboutLiz["app/about/index.liz"]:::doc
        LayoutLiz["app/layout.liz"]:::doc

        GlobalCSS["styles.css (global)"]:::doc
        CSSModule["Button.module.css (CSS Modules)"]:::doc

        TwInput["input.css (Tailwind input)"]:::doc
        TwBuild["Tailwind Build Step"]:::tool
        TwConfig["tailwind.config.js"]:::tool
        TwCSSOut["generated CSS (Tailwind output)"]:::artifact
    end

    AppBasic -->|"contains"| LizIndex
    AppBasic -->|"imports"| GlobalCSS

    AppElizabeth -->|"contains"| AboutLiz
    AppElizabeth -->|"contains"| LayoutLiz
    AppElizabeth -->|"imports"| CSSModule

    AppLizTw -->|"contains"| TwInput
    AppLizTw -->|"configured by"| TwConfig
    TwBuild -->|"reads"| TwInput
    TwBuild -->|"uses"| TwConfig
    TwBuild -->|"writes"| TwCSSOut

    %% ========= Generated artifacts / cache =========
    subgraph CacheLayer["Derived Outputs"]
        direction TB
        CacheEliz[".elizabeth/cache (generated TSX)"]:::cache
        CacheLizTw[".elizabeth/cache (Tailwind example)"]:::cache
        CacheFile["Generated TSX Module (*.tsx)"]:::artifact
    end

    CacheEliz -->|"includes"| CacheFile

    %% ========= Dev/build flows =========
    DevServer <-->|"resolve route <-> file path"| Router

    Router -->|"maps URL -> app/**/index.liz"| AboutLiz
    Router -->|"maps URL -> app/index.liz"| LizIndex

    DevServer -->|"on-demand/changed file"| Transpiler
    Transpiler -->|"reads"| LizIndex
    Transpiler -->|"reads"| AboutLiz
    Transpiler -->|"reads"| LayoutLiz
    Transpiler -->|"reads"| GlobalCSS
    Transpiler -->|"reads (hash classnames)"| CSSModule
    Transpiler -.->|"writes derived TSX"| CacheEliz
    Transpiler -.->|"writes derived TSX"| CacheLizTw

    DevServer -->|"loads compiled module"| CacheEliz
    DevServer -->|"loads compiled module"| CacheLizTw
    DevServer -->|"render(vdom) -> HTML"| CoreSSR
    CoreSSR -->|"HTML + island markers + island manifest"| IslandScripts

    %% ========= Request/response + hydration (runtime) =========
    Browser -->|"HTTP GET /route"| DevServer
    DevServer -->|"HTTP response: HTML"| Browser

    Browser -->|"loads hydration runtime"| ClientRuntime
    Browser -->|"loads per-island scripts"| IslandScripts
    Browser -->|"loads CSS (global/modules/tailwind)"| GlobalCSS
    Browser -->|"loads CSS Modules output"| CSSModule
    Browser -->|"loads Tailwind output CSS"| TwCSSOut

    ClientRuntime -->|"partial hydration (islands only)"| Browser
    ClientRuntime -->|"useState + events active in islands"| Browser

    %% ========= Notes / callouts =========
    NoteSSR["SSR first: render(vdom) -> HTML"]:::note
    NoteIslands["Islands Architecture: partial hydration per component"]:::note
    NoteRoutes["File-based routing: app/about/index.liz -> /about"]:::note
    NoteCSS["CSS Modules: className hashing; Tailwind: prebuilt CSS"]:::note

    CoreSSR -->|"SSR"| NoteSSR
    IslandDetect -->|"event handlers (onClick, ...)"| NoteIslands
    Router -->|"routes"| NoteRoutes
    Transpiler -->|"style transforms"| NoteCSS

    %% ========= Click events (paths only; not visible) =========
    click CLIWrap "https://github.com/liz-origin/elizabeth/tree/master/bin/elizabeth"
    click CLILogic "https://github.com/liz-origin/elizabeth/blob/master/src/cli.ts"
    click DevServer "https://github.com/liz-origin/elizabeth/blob/master/src/framework/server.ts"
    click Router "https://github.com/liz-origin/elizabeth/blob/master/src/framework/router.ts"
    click Transpiler "https://github.com/liz-origin/elizabeth/blob/master/src/transpile.ts"
    click CoreSSR "https://github.com/liz-origin/elizabeth/blob/master/src/core.ts"
    click APISurface "https://github.com/liz-origin/elizabeth/blob/master/src/index.tsx"
    click ClientRuntime "https://github.com/liz-origin/elizabeth/blob/master/src/framework/client.ts"

    click LizIndex "https://github.com/liz-origin/elizabeth/blob/master/examples/basic-app/app/index.liz"
    click AboutLiz "https://github.com/liz-origin/elizabeth/blob/master/examples/elizabeth/app/about/index.liz"
    click LayoutLiz "https://github.com/liz-origin/elizabeth/blob/master/examples/elizabeth/app/layout.liz"
    click GlobalCSS "https://github.com/liz-origin/elizabeth/blob/master/examples/basic-app/app/styles.css"
    click CSSModule "https://github.com/liz-origin/elizabeth/blob/master/examples/elizabeth/app/Button.module.css"

    click CacheEliz "https://github.com/liz-origin/elizabeth/blob/master/examples/elizabeth/.elizabeth/cache"
    click CacheFile "https://github.com/liz-origin/elizabeth/blob/master/examples/elizabeth/.elizabeth/cache/HomePage_2x9jbh2f1p1ge.tsx"

    click TwBuild "https://github.com/liz-origin/elizabeth/blob/master/examples/liz-tw/build-tailwind.ts"
    click TwConfig "https://github.com/liz-origin/elizabeth/blob/master/examples/liz-tw/tailwind.config.js"
    click TwInput "https://github.com/liz-origin/elizabeth/blob/master/examples/liz-tw/app/input.css"
    click CacheLizTw "https://github.com/liz-origin/elizabeth/blob/master/examples/liz-tw/.elizabeth/cache"

    %% ========= Styles =========
    classDef actor fill:#2f2f2f,stroke:#111,stroke-width:1px,color:#fff
    classDef boundary fill:#0b1020,stroke:#2b5cff,stroke-width:1px,color:#e8eeff
    classDef tool fill:#1f4b99,stroke:#0c2a66,stroke-width:1px,color:#ffffff
    classDef server fill:#2b7bbb,stroke:#0f3a5a,stroke-width:1px,color:#ffffff
    classDef compiler fill:#2e8b57,stroke:#165a37,stroke-width:1px,color:#ffffff
    classDef client fill:#d97706,stroke:#92400e,stroke-width:1px,color:#fff7ed
    classDef app fill:#6b7280,stroke:#374151,stroke-width:1px,color:#ffffff
    classDef doc fill:#9ca3af,stroke:#4b5563,stroke-width:1px,color:#111827
    classDef cache fill:#10b981,stroke:#065f46,stroke-width:1px,color:#06281f
    classDef artifact fill:#34d399,stroke:#065f46,stroke-width:1px,color:#052e23
    classDef note fill:#fde68a,stroke:#b45309,stroke-width:1px,color:#111827
```
