# minirang/jeomlang architecture

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

- Interactive diagram: https://gitdiagram.com/minirang/jeomlang
- Repository: https://github.com/minirang/jeomlang

## Overview

1. **What this repo is**
   - This is a small language ecosystem centered on **Jeom**: a language/runtime implementation, its standard library, examples, docs, and a couple of browser-based surfaces for running or presenting it.
   - The architecture is split between the **execution core** and multiple **tooling/UI layers** that consume that core.

2. **Core runtime**
   - `core/engine.js` is the main execution engine for Jeom.
   - `core/cli.js` is the command-line entry point that wraps the engine and exposes it to local users.
   - This is the primary backend boundary: source programs flow into the engine, and results/errors come back out through the CLI or other consumers.

3. **Language standard library and sample programs**
   - `stdlib/std.jeom` is the built-in standard library shipped with the language.
   - `examples/*.jeom` are canonical programs demonstrating syntax and runtime behavior (calculator, factorial, Fibonacci, Hanoi, etc.).
   - These files show the expected input format for the engine and act as integration smoke tests for language features.

4. **Specification and documentation**
   - `docs/SPEC.md` is the authoritative language specification.
   - `docs/CHANGELOG.md` tracks user-visible release changes.
   - `GRAMMAR.md` likely describes the parsing grammar, making it a key artifact for understanding language syntax and parser boundaries.

5. **Browser IDE**
   - `ide/src/ide.ts` is the TypeScript source for the in-browser IDE.
   - `ide/dist/ide.js` is the built client bundle, while `ide/index.html` and `ide/ide.css` provide the shell and styling.
   - This subsystem is a separate frontend boundary that likely lets users edit/run Jeom code without the CLI.

6. **Public homepage / landing site**
   - `home/index.html`, `home/index.js`, and `home/style.css` make up a lightweight static site.
   - `assets/img` contains shared imagery used by the public-facing pages.
   - This is presentation-only and separate from the language runtime and IDE.

7. **Shared frontend components**
   - `shared/custom-elements.js` contains reusable web components or UI primitives shared across browser surfaces.
   - This suggests some deliberate front-end reuse between the homepage and IDE, reducing duplication at the UI boundary.

8. **Developer tooling**
   - `tools/formatter/formatter.py` is a Python-based formatter for Jeom source, indicating language tooling is not limited to JavaScript/TypeScript.
   - `tools/vscode-extension/` suggests an editor integration exists or is being scaffolded, though the presence of `temp` implies it may be incomplete or transitional.
   - These tools consume the same language syntax/spec as the core runtime but are outside the execution path.

9. **Build and deployment**
   - `package.json`, `tsconfig.json`, and the checked-in `ide/dist/ide.js` indicate a build step for the TypeScript frontend.
   - `vercel.json` suggests at least one static deployment target, likely for the homepage and/or IDE.
   - `.github/workflows/update-changelog.yml` automates release-note maintenance.

10. **Repository shape and boundaries**
   - The repo is intentionally multi-surface: **runtime**, **CLI**, **docs/spec**, **examples**, **web IDE**, **homepage**, and **tooling**.
   - The main data flow is: Jeom source code → core engine/runtime → output/errors, with the same language definition reused by docs, formatter, IDE, and examples.
   - In an architecture diagram, the core engine should sit at the center, with the CLI and browser IDE as separate clients, and the standard library/examples/docs/tooling as supporting layers around it.

Main entry points: [`core/engine.js`](https://github.com/minirang/jeomlang/blob/main/core/engine.js) (Engine), [`docs/SPEC.md`](https://github.com/minirang/jeomlang/blob/main/docs/SPEC.md) (Spec), [`shared/custom-elements.js`](https://github.com/minirang/jeomlang/blob/main/shared/custom-elements.js) (Shared UI), [`GRAMMAR.md`](https://github.com/minirang/jeomlang/blob/main/GRAMMAR.md) (Grammar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_engine["Engine<br/>runtime core<br/>[engine.js]"]
  node_cli["CLI<br/>runtime entry<br/>[cli.js]"]
end

subgraph group_language["Language Spec"]
  node_stdlib["Stdlib<br/>language library<br/>[std.jeom]"]
  node_examples["Examples<br/>language samples"]
end

subgraph group_frontend["Browser UI"]
  node_ide_src["IDE Source<br/>frontend source<br/>[ide.ts]"]
  node_ide_bundle["IDE Bundle<br/>frontend build<br/>[ide.js]"]
  node_ide_shell["IDE Shell<br/>frontend shell<br/>[index.html]"]
  node_home_site["Homepage<br/>static site<br/>[index.html]"]
  node_shared_ui["Shared UI<br/>web components<br/>[custom-elements.js]"]
end

subgraph group_docs["Docs"]
  node_grammar["Grammar<br/>syntax spec<br/>[GRAMMAR.md]"]
  node_spec["Spec<br/>[SPEC.md]"]
  node_changelog["Changelog<br/>release notes<br/>[CHANGELOG.md]"]
end

subgraph group_tooling["Tooling"]
  node_formatter["Formatter<br/>language tooling<br/>[formatter.py]"]
  node_vscode_ext["VS Code<br/>editor integration"]
end

subgraph group_ops["Ops"]
  node_workflow["Changelog CI<br/>automation"]
  node_deploy["Deploy<br/>hosting config<br/>[vercel.json]"]
end

node_cli -->|"invokes"| node_engine
node_stdlib -->|"loads"| node_engine
node_examples -->|"exercises"| node_engine
node_grammar -->|"informs"| node_spec
node_spec -->|"defines"| node_engine
node_grammar -->|"parses"| node_engine
node_ide_src -->|"builds"| node_ide_bundle
node_ide_shell -->|"hosts"| node_ide_bundle
node_shared_ui -->|"shared with"| node_ide_shell
node_shared_ui -->|"shared with"| node_home_site
node_ide_src -->|"runs code"| node_engine
node_home_site -->|"uses"| node_shared_ui
node_formatter -->|"follows"| node_spec
node_formatter -->|"follows"| node_grammar
node_vscode_ext -->|"integrates"| node_spec
node_workflow -->|"updates"| node_changelog
node_deploy -->|"deploys"| node_home_site
node_deploy -->|"deploys"| node_ide_shell

click node_engine "https://github.com/minirang/jeomlang/blob/main/core/engine.js"
click node_cli "https://github.com/minirang/jeomlang/blob/main/core/cli.js"
click node_stdlib "https://github.com/minirang/jeomlang/blob/main/stdlib/std.jeom"
click node_examples "https://github.com/minirang/jeomlang/tree/main/examples"
click node_grammar "https://github.com/minirang/jeomlang/blob/main/GRAMMAR.md"
click node_spec "https://github.com/minirang/jeomlang/blob/main/docs/SPEC.md"
click node_changelog "https://github.com/minirang/jeomlang/blob/main/docs/CHANGELOG.md"
click node_ide_src "https://github.com/minirang/jeomlang/blob/main/ide/src/ide.ts"
click node_ide_bundle "https://github.com/minirang/jeomlang/blob/main/ide/dist/ide.js"
click node_ide_shell "https://github.com/minirang/jeomlang/blob/main/ide/index.html"
click node_home_site "https://github.com/minirang/jeomlang/blob/main/home/index.html"
click node_shared_ui "https://github.com/minirang/jeomlang/blob/main/shared/custom-elements.js"
click node_formatter "https://github.com/minirang/jeomlang/blob/main/tools/formatter/formatter.py"
click node_vscode_ext "https://github.com/minirang/jeomlang/tree/main/tools/vscode-extension"
click node_workflow "https://github.com/minirang/jeomlang/blob/main/.github/workflows/update-changelog.yml"
click node_deploy "https://github.com/minirang/jeomlang/blob/main/vercel.json"

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_engine,node_cli toneBlue
class node_stdlib,node_examples toneAmber
class node_ide_src,node_ide_bundle,node_ide_shell,node_home_site,node_shared_ui toneMint
class node_grammar,node_spec,node_changelog toneRose
class node_formatter,node_vscode_ext toneIndigo
class node_workflow,node_deploy toneTeal
```

## Components

### Runtime

Language execution core and entrypoints

- [Engine](https://github.com/minirang/jeomlang/blob/main/core/engine.js): runtime core · Main Jeom execution engine · `core/engine.js`
- [CLI](https://github.com/minirang/jeomlang/blob/main/core/cli.js): runtime entry · Command-line wrapper around the engine · `core/cli.js`

### Language Spec

Grammar, standard library, and example programs

- [Stdlib](https://github.com/minirang/jeomlang/blob/main/stdlib/std.jeom): language library · Built-in standard library shipped with Jeom · `stdlib/std.jeom`
- [Examples](https://github.com/minirang/jeomlang/tree/main/examples): language samples · Canonical Jeom programs demonstrating features · `examples`

### Browser UI

Web surfaces built around the language

- [IDE Source](https://github.com/minirang/jeomlang/blob/main/ide/src/ide.ts): frontend source · TypeScript source for the browser IDE · `ide/src/ide.ts`
- [IDE Bundle](https://github.com/minirang/jeomlang/blob/main/ide/dist/ide.js): frontend build · Built client bundle for the IDE · `ide/dist/ide.js`
- [IDE Shell](https://github.com/minirang/jeomlang/blob/main/ide/index.html): frontend shell · HTML and CSS shell for the browser IDE · `ide/index.html`
- [Homepage](https://github.com/minirang/jeomlang/blob/main/home/index.html): static site · Public landing page and supporting script/style · `home/index.html`
- [Shared UI](https://github.com/minirang/jeomlang/blob/main/shared/custom-elements.js): web components · Reusable browser UI primitives · `shared/custom-elements.js`

### Docs

Project and release documentation

- [Grammar](https://github.com/minirang/jeomlang/blob/main/GRAMMAR.md): syntax spec · Parsing grammar and syntax reference · `GRAMMAR.md`
- [Spec](https://github.com/minirang/jeomlang/blob/main/docs/SPEC.md): language spec · Authoritative language specification · `docs/SPEC.md`
- [Changelog](https://github.com/minirang/jeomlang/blob/main/docs/CHANGELOG.md): release notes · User-visible release history · `docs/CHANGELOG.md`

### Tooling

Developer and editor integrations

- [Formatter](https://github.com/minirang/jeomlang/blob/main/tools/formatter/formatter.py): language tooling · Python formatter for Jeom source · `tools/formatter/formatter.py`
- [VS Code](https://github.com/minirang/jeomlang/tree/main/tools/vscode-extension): editor integration · VS Code extension scaffold or integration area · `tools/vscode-extension`

### Ops

Build, package, and deployment config

- [Changelog CI](https://github.com/minirang/jeomlang/blob/main/.github/workflows/update-changelog.yml): automation · GitHub Actions workflow for changelog updates · `.github/workflows/update-changelog.yml`
- [Deploy](https://github.com/minirang/jeomlang/blob/main/vercel.json): hosting config · Deployment configuration for static surfaces · `vercel.json`

## Connections

- CLI → Engine: invokes · CLI delegates program execution to the runtime
- Stdlib → Engine: loads · Standard library is executed or imported by the engine
- Examples → Engine: exercises · Example programs are canonical inputs for the runtime
- Grammar → Spec: informs · Grammar is part of the language definition and supports the spec
- Spec → Engine: defines · Specification constrains engine behavior
- Grammar → Engine: parses · Grammar guides parsing and syntax handling in the runtime
- IDE Source → IDE Bundle: builds · TypeScript source compiles into the browser bundle
- IDE Shell → IDE Bundle: hosts · HTML shell loads the built IDE client
- Shared UI → IDE Shell: shared with · Browser UI primitives are reused in the IDE surface
- Shared UI → Homepage: shared with · Reusable components also support the homepage
- IDE Source → Engine: runs code · IDE is a browser-facing client of the runtime
- Homepage → Shared UI: uses · Homepage consumes shared frontend components
- Formatter → Spec: follows · Formatter implements the language rules described by the spec
- Formatter → Grammar: follows · Formatter also depends on syntax structure
- VS Code → Spec: integrates · Editor tooling is aligned with the language definition
- Changelog CI → Changelog: updates · Automation maintains release notes
- Deploy → Homepage: deploys · Static hosting config targets the public site
- Deploy → IDE Shell: deploys · Static hosting config also supports the IDE surface
