# harrysolovay/liminal architecture

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

- Interactive diagram: https://gitdiagram.com/harrysolovay/liminal
- Repository: https://github.com/harrysolovay/liminal

## Overview

##### Project type and purpose
- Liminal is a multi-package TypeScript “toolkit” monorepo for composing conversation trees over LLMs via iterator/generator-based APIs.
- It consists of:
- A core library (`/liminal`) that defines runes, strands, adapters, context, schemas, etc.
- A suite of official adapter packages (`/packages/liminal-*`) that plug in different LLM providers.
- Example integrations (`/example-integrations/*`) showing usage in CF Workers, Hono HTTP servers, Vite + React apps, Docker Compose, etc.
- A VitePress-based documentation site (`/liminal.land`).
- Test harness rules (`/.cursor`) and example scripts (`/examples`).

##### File structure
- Top-level directories:
- `liminal/` → core engine code
- `packages/` → NPM plugin packages (openai, alchemy, ark-type, etc.)
- `example-integrations/` → runnable sample projects
- `examples/` → minimal TS scripts demonstrating library features
- `liminal.land/` → docs site
- `.cursor/` → testing rules
- Config files: `tsconfig.*.json`, `bun.lock`, `vitest.ts`, GitHub workflows under `/.github/workflows`.
- The core uses a plugin architecture (AdapterRegistry), generator patterns (yield runes), and modular packaging.

##### README for additional insights
- Core concept: generators yield runes (`L.user`, `L.assistant`, `L.strand`, `L.focus`) to mutate conversation state or call out to an LLM via an adapter.
- Entry point: `L.run(generatorFn, { handler })`
- Adapters are pluggable; examples use `liminal-ollama`, etc.
- Documentation lives on `liminal.land`, examples under `/examples`.

##### Main components & relationships

A. Core library (`liminal/`)
- Modules: AdapterRegistry, Config, Context, Definition, Message, Rune engine, Schema, Strand, Tool interfaces
- Patterns: generator/rune pipeline, event emission (LEvent), error handling

B. Adapter packages (`/packages/liminal-<provider>`)
- Each implements the `Adapter` interface and registers to AdapterRegistry
- Examples: liminal-openai, liminal-ollama, liminal-alchemy, etc.

C. Runtime environment(s) from example-integrations
- Cloudflare Worker
- Hono HTTP Server
- Vite + React SPA (with PGLite Web Worker)
- Docker Compose (local LLM stack)
- They import `liminal` + one or more `/packages/liminal-*` adapters, then call `L.run()`

D. External LLM services
- OpenAI API
- Ollama
- Alchemy
- Other HTTP/GRPC endpoints

E. Documentation site
- Built with VitePress, live at `liminal.land`
- Pulls markdown in `/liminal.land` and references code examples

F. Testing & CI
- `.cursor` test rules
- Vitest config (`vitest.ts`)
- GitHub Actions workflows for build, test, deploy

##### Architectural patterns & design principles
- Monorepo with workspaces: core + plugins + docs + examples
- Plugin architecture: AdapterRegistry + modular adapter packages
- Generator-based DSL (“runes”) for stateful conversation modeling
- Strict TypeScript typing with schema modules under `liminal/L/schema`

##### Elements to capture
- File-structure boundaries: show top-level workspaces
- Plugin registration: AdapterRegistry receives providers at runtime
- External dependencies: HTTP requests to LLM endpoints
- CI triggers: GitHub Actions building core, publishing packages, deploying docs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library (liminal/)"
        direction TB
        AR["AdapterRegistry"]:::core
        CFG["Config"]:::core
        CTX["Context"]:::core
        DEF["Definition"]:::core
        RE["Rune Engine"]:::core
        SCH["Schema Definitions"]:::core
        STR["Strand"]:::core
        TOL["Tool Interface"]:::core
        EVT["Event System"]:::core
        IDX["Core Index"]:::core
    end

    %% Adapter Packages
    subgraph "Adapter Packages (packages/liminal-*)"
        direction TB
        OAI["Adapter: liminal-openai"]:::adapter
        OLL["Adapter: liminal-ollama"]:::adapter
        ALC["Adapter: liminal-alchemy"]:::adapter
        AI["Adapter: liminal-ai"]:::adapter
        ART["Adapter: liminal-arktype"]:::adapter
        EFF["Adapter: liminal-effect"]:::adapter
        INC["Adapter: liminal-inception"]:::adapter
        TBX["Adapter: liminal-typebox"]:::adapter
        VLB["Adapter: liminal-valibot"]:::adapter
        ZOD["Adapter: liminal-zod3"]:::adapter
    end

    %% Example Integrations
    subgraph "Example Integrations"
        direction TB
        CF["Cloudflare Worker"]:::examples
        HN["Hono HTTP Server"]:::examples
        VR["Vite + React SPA"]:::examples
        DC["Docker Compose"]:::examples
    end

    %% Minimal Feature Scripts
    subgraph "Minimal Feature Scripts (examples/)"
        direction TB
        MS["Sample Scripts"]:::examples
    end

    %% Documentation Site
    subgraph "Documentation Site (liminal.land/)"
        direction TB
        DOC["VitePress Docs"]:::docs
    end

    %% CI & Testing
    subgraph "CI & Testing"
        direction TB
        CUR[".cursor Test Rules"]:::ci
        VIT["Vitest Config"]:::ci
        GHA["GitHub Actions Workflows"]:::ci
    end

    %% External LLM Services
    subgraph "External LLM Services"
        direction TB
        EA["OpenAI API"]:::external
        EB["Ollama"]:::external
        EC["Alchemy API"]:::external
        ED["Other LLM Endpoints"]:::external
    end

    %% Connections
    CF -->|imports L.run| AR
    HN -->|imports L.run| AR
    VR -->|imports L.run| AR
    DC -->|imports L.run| AR
    MS -->|calls L.run| AR

    AR -->|"uses"| OAI
    AR -->|"uses"| OLL
    AR -->|"uses"| ALC
    AR -->|"uses"| AI
    AR -->|"uses"| ART
    AR -->|"uses"| EFF
    AR -->|"uses"| INC
    AR -->|"uses"| TBX
    AR -->|"uses"| VLB
    AR -->|"uses"| ZOD

    OAI -->|HTTP| EA
    OLL -->|HTTP| EB
    ALC -->|HTTP| EC
    AI -->|HTTP| ED
    ART -->|HTTP| ED
    EFF -->|HTTP| ED
    INC -->|HTTP| ED
    TBX -->|HTTP| ED
    VLB -->|HTTP| ED
    ZOD -->|HTTP| ED

    AR -->|dashed| CUR
    AR -->|dashed| VIT
    AR -->|dashed| GHA

    AR -->|references| DOC
    MS -->|references| DOC
    CF -->|references| DOC

    %% Click Events - Core
    click AR "https://github.com/harrysolovay/liminal/blob/main/liminal/AdapterRegistry.ts"
    click CFG "https://github.com/harrysolovay/liminal/blob/main/liminal/Config.ts"
    click CTX "https://github.com/harrysolovay/liminal/blob/main/liminal/Context.ts"
    click DEF "https://github.com/harrysolovay/liminal/blob/main/liminal/Definition.ts"
    click RE "https://github.com/harrysolovay/liminal/blob/main/liminal/Rune.ts"
    click SCH "https://github.com/harrysolovay/liminal/tree/main/liminal/L/schema/"
    click STR "https://github.com/harrysolovay/liminal/blob/main/liminal/Strand.ts"
    click TOL "https://github.com/harrysolovay/liminal/blob/main/liminal/Tool.ts"
    click EVT "https://github.com/harrysolovay/liminal/blob/main/liminal/LEvent.ts"
    click IDX "https://github.com/harrysolovay/liminal/blob/main/liminal/index.ts"

    %% Click Events - Adapters
    click OAI "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-openai/index.ts"
    click OLL "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-ollama/index.ts"
    click ALC "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-alchemy/index.ts"
    click AI "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-ai/index.ts"
    click ART "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-arktype/index.ts"
    click EFF "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-effect/index.ts"
    click INC "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-inception/index.ts"
    click TBX "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-typebox/index.ts"
    click VLB "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-valibot/index.ts"
    click ZOD "https://github.com/harrysolovay/liminal/blob/main/packages/liminal-zod3/index.ts"

    %% Click Events - Example Integrations
    click CF "https://github.com/harrysolovay/liminal/blob/main/example-integrations/deploy-to-cf-worker/worker/worker.ts"
    click HN "https://github.com/harrysolovay/liminal/blob/main/example-integrations/hono/server.ts"
    click VR "https://github.com/harrysolovay/liminal/blob/main/example-integrations/vite-react-app/src/App.tsx"
    click DC "https://github.com/harrysolovay/liminal/blob/main/example-integrations/docker-compose.yml"

    %% Click Events - Examples
    click MS "https://github.com/harrysolovay/liminal/tree/main/examples/"

    %% Click Events - Docs
    click DOC "https://github.com/harrysolovay/liminal/tree/main/liminal.land/"

    %% Click Events - CI & Testing
    click CUR "https://github.com/harrysolovay/liminal/tree/main/.cursor/rules/"
    click VIT "https://github.com/harrysolovay/liminal/blob/main/vitest.ts"
    click GHA "https://github.com/harrysolovay/liminal/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5
    classDef adapter fill:#bbdefb,stroke:#1e88e5
    classDef examples fill:#bbdefb,stroke:#1e88e5
    classDef docs fill:#bbdefb,stroke:#1e88e5
    classDef external fill:#c8e6c9,stroke:#43a047
    classDef ci fill:#eeeeee,stroke:#757575
```
