# erishen/lume architecture

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

- Interactive diagram: https://gitdiagram.com/erishen/lume
- Repository: https://github.com/erishen/lume

## Overview

Lume is a C11 interpreter-backed web framework: developers write `.lume` business scripts, and the runtime parses, checks, and executes them to serve web pages, JSON APIs, and registered tools. The README also documents native SQLite, SSE chat/LLM agent tools, SSR, and multi-file modules. The graph includes documented demo branches as well as sampled runtime layers; `agent-httpd` is a documented submodule but is absent from the supplied tree, so its internals are not expanded.

Main entry points: [`src/interp.c`](https://github.com/erishen/lume/blob/main/src/interp.c) (Interpreter), [`src/parser.c`](https://github.com/erishen/lume/blob/main/src/parser.c) (Parser), [`frontend/react-ssr/server/main.tsx`](https://github.com/erishen/lume/blob/main/frontend/react-ssr/server/main.tsx) (Resident SSR server), [`src/main.c`](https://github.com/erishen/lume/blob/main/src/main.c) (Runtime entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language runtime"]
  node_main["Runtime entry<br/>[main.c]"]
  node_lexer["Lexer<br/>[lexer.c]"]
  node_parser["Parser<br/>[parser.c]"]
  node_statements["Statement parser<br/>[parser_stmt.c]"]
  node_typecheck["Type checker<br/>[typecheck.c]"]
  node_interpreter["Interpreter<br/>[interp.c]"]
  node_values["Values and types<br/>[value.c]"]
  node_builtins["Built-ins<br/>[builtins.c]"]
end

subgraph group_web["Web and integrations"]
  node_bridge["HTTP bridge<br/>[bridge.c]"]
  node_agenthttpd["HTTP/chat service"]
  node_sqlite[("SQLite database")]
end

subgraph group_examples["Product demonstrations"]
  node_invest["Portfolio assistant UI<br/>[app.tsx]"]
  node_hub["Capability hub UI<br/>[hub-home.tsx]"]
  node_abac["ABAC demo UI<br/>[app.tsx]"]
  node_modules["Modules tax UI<br/>[app.tsx]"]
end

subgraph group_ssr["React SSR demo"]
  node_reactui["React route app<br/>[App.tsx]"]
  node_ssrserver["Resident SSR server<br/>[main.tsx]"]
  node_ssrrender["SSR renderer<br/>[render.tsx]"]
  node_hydrate["Hydration client<br/>[client.tsx]"]
end

node_developer(("Script author"))
node_script["Lume script"]
node_llm["LLM provider"]
node_browser(("Browser user"))

node_developer -->|"writes"| node_script
node_script -->|"runs"| node_main
node_main -->|"lexes"| node_lexer
node_lexer -->|"tokens"| node_parser
node_parser -->|"parses statements"| node_statements
node_parser -->|"AST"| node_typecheck
node_typecheck -->|"checked program"| node_interpreter
node_interpreter -->|"evaluates"| node_values
node_interpreter -->|"dispatches"| node_builtins
node_interpreter -->|"registers routes"| node_bridge
node_bridge -->|"configures"| node_agenthttpd
node_agenthttpd -->|"serves pages and APIs"| node_browser
node_browser -->|"uses"| node_invest
node_browser -->|"uses"| node_hub
node_browser -->|"uses"| node_abac
node_browser -->|"uses"| node_modules
node_browser -->|"sends chat requests"| node_agenthttpd
node_agenthttpd -.->|"requests generation"| node_llm
node_agenthttpd -->|"accesses"| node_sqlite
node_browser -->|"requests page"| node_ssrserver
node_ssrserver -->|"renders"| node_ssrrender
node_ssrrender -->|"renders tree"| node_reactui
node_ssrserver -->|"streams HTML"| node_browser
node_browser -->|"loads client"| node_hydrate
node_hydrate -->|"hydrates"| node_reactui

click node_main "https://github.com/erishen/lume/blob/main/src/main.c"
click node_lexer "https://github.com/erishen/lume/blob/main/src/lexer.c"
click node_parser "https://github.com/erishen/lume/blob/main/src/parser.c"
click node_statements "https://github.com/erishen/lume/blob/main/src/parser_stmt.c"
click node_typecheck "https://github.com/erishen/lume/blob/main/src/typecheck.c"
click node_interpreter "https://github.com/erishen/lume/blob/main/src/interp.c"
click node_values "https://github.com/erishen/lume/blob/main/src/value.c"
click node_builtins "https://github.com/erishen/lume/blob/main/src/builtins.c"
click node_bridge "https://github.com/erishen/lume/blob/main/src/bridge.c"
click node_invest "https://github.com/erishen/lume/blob/main/frontend/src/invest/app.tsx"
click node_hub "https://github.com/erishen/lume/blob/main/frontend/src/hub/hub-home.tsx"
click node_abac "https://github.com/erishen/lume/blob/main/frontend/src/abac/app.tsx"
click node_modules "https://github.com/erishen/lume/blob/main/frontend/src/modules/app.tsx"
click node_reactui "https://github.com/erishen/lume/blob/main/frontend/react-ssr/App.tsx"
click node_ssrserver "https://github.com/erishen/lume/blob/main/frontend/react-ssr/server/main.tsx"
click node_ssrrender "https://github.com/erishen/lume/blob/main/frontend/react-ssr/server/render.tsx"
click node_hydrate "https://github.com/erishen/lume/blob/main/frontend/react-ssr/client.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_lexer,node_parser,node_statements,node_typecheck,node_interpreter,node_values,node_builtins,node_browser toneBlue
class node_bridge,node_agenthttpd,node_sqlite toneAmber
class node_invest,node_hub,node_abac,node_modules toneMint
class node_reactui,node_ssrserver,node_ssrrender,node_hydrate toneRose
class node_developer,node_script,node_llm toneIndigo
```

## Components

### Language runtime

- [Runtime entry](https://github.com/erishen/lume/blob/main/src/main.c): `src/main.c`
- [Lexer](https://github.com/erishen/lume/blob/main/src/lexer.c): `src/lexer.c`
- [Parser](https://github.com/erishen/lume/blob/main/src/parser.c): `src/parser.c`
- [Statement parser](https://github.com/erishen/lume/blob/main/src/parser_stmt.c): `src/parser_stmt.c`
- [Type checker](https://github.com/erishen/lume/blob/main/src/typecheck.c): `src/typecheck.c`
- [Interpreter](https://github.com/erishen/lume/blob/main/src/interp.c): `src/interp.c`
- [Values and types](https://github.com/erishen/lume/blob/main/src/value.c): `src/value.c`
- [Built-ins](https://github.com/erishen/lume/blob/main/src/builtins.c): `src/builtins.c`

### Web and integrations

- [HTTP bridge](https://github.com/erishen/lume/blob/main/src/bridge.c): `src/bridge.c`
- **HTTP/chat service**
- **SQLite database**

### Product demonstrations

- [Portfolio assistant UI](https://github.com/erishen/lume/blob/main/frontend/src/invest/app.tsx): `frontend/src/invest/app.tsx`
- [Capability hub UI](https://github.com/erishen/lume/blob/main/frontend/src/hub/hub-home.tsx): `frontend/src/hub/hub-home.tsx`
- [ABAC demo UI](https://github.com/erishen/lume/blob/main/frontend/src/abac/app.tsx): `frontend/src/abac/app.tsx`
- [Modules tax UI](https://github.com/erishen/lume/blob/main/frontend/src/modules/app.tsx): `frontend/src/modules/app.tsx`

### React SSR demo

- [React route app](https://github.com/erishen/lume/blob/main/frontend/react-ssr/App.tsx): `frontend/react-ssr/App.tsx`
- [Resident SSR server](https://github.com/erishen/lume/blob/main/frontend/react-ssr/server/main.tsx): `frontend/react-ssr/server/main.tsx`
- [SSR renderer](https://github.com/erishen/lume/blob/main/frontend/react-ssr/server/render.tsx): `frontend/react-ssr/server/render.tsx`
- [Hydration client](https://github.com/erishen/lume/blob/main/frontend/react-ssr/client.tsx): `frontend/react-ssr/client.tsx`

### Other components

- **Script author**
- **Lume script**
- **LLM provider**
- **Browser user**

## Connections

- Script author → Lume script: writes
- Lume script → Runtime entry: runs
- Runtime entry → Lexer: lexes
- Lexer → Parser: tokens
- Parser → Statement parser: parses statements
- Parser → Type checker: AST
- Type checker → Interpreter: checked program
- Interpreter → Values and types: evaluates
- Interpreter → Built-ins: dispatches
- Interpreter → HTTP bridge: registers routes
- HTTP bridge → HTTP/chat service: configures
- HTTP/chat service → Browser user: serves pages and APIs
- Browser user → Portfolio assistant UI: uses
- Browser user → Capability hub UI: uses
- Browser user → ABAC demo UI: uses
- Browser user → Modules tax UI: uses
- Browser user → HTTP/chat service: sends chat requests
- HTTP/chat service → LLM provider: requests generation
- HTTP/chat service → SQLite database: accesses
- Browser user → Resident SSR server: requests page
- Resident SSR server → SSR renderer: renders
- SSR renderer → React route app: renders tree
- Resident SSR server → Browser user: streams HTML
- Browser user → Hydration client: loads client
- Hydration client → React route app: hydrates