# jarbear82/hyperql architecture

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

- Interactive diagram: https://gitdiagram.com/jarbear82/hyperql
- Repository: https://github.com/jarbear82/hyperql

## Overview

1. **Repo purpose**
   - This repository is a language-tooling stack for HyperQL, a graph-relational query language.
   - It is not an application backend; it is centered on parsing, editor support, and language-server integration.

2. **Source-of-truth language assets**
   - `hyperql-language-specification/` holds versioned JSON specifications for language editions `0-17`, `0-18`, and `0-19`.
   - That folder also includes example `.hql` files and design notes/proposals, which serve as the human-readable reference material for the language.

3. **Tree-sitter grammar package**
   - `tree-sitter-hyperql/` is the core parser project.
   - It contains the grammar definition (`grammar.js`) plus generated parser artifacts in `src/` such as `parser.c`, `grammar.json`, and `node-types.json`.
   - This is the main boundary where language syntax becomes an executable parse tree.

4. **Multi-language parser bindings**
   - The Tree-sitter package exposes bindings for C, Go, Java, Node.js, Python, Rust, and Zig under `bindings/`.
   - These bindings let other tools embed the HyperQL parser without reimplementing the grammar.
   - Architecturally, this makes the parser the shared core consumed by editor tooling and any external integrations.

5. **Editor extension layer for Zed**
   - `hyperql-zed/` is the Zed editor extension, implemented as a Rust crate.
   - It ships a compiled grammar artifact (`grammars/hyperql.wasm`) and Tree-sitter query files for syntax features: `highlights.scm`, `indents.scm`, and `outline.scm`.
   - `languages/hyperql/config.toml` defines editor-facing language configuration for Zed.

6. **Language-server layer**
   - `hyperql-lsp/` is a separate Zig-based Language Server Protocol server.
   - The README indicates it provides at least basic diagnostics.
   - This layer is the runtime bridge between the language grammar and editor feedback, independent from the Zed extension packaging.

7. **Primary runtime/data flow**
   - HyperQL language definitions and examples inform the grammar in `tree-sitter-hyperql/`.
   - The Tree-sitter parser produces parse trees used by editor queries and by any bindings.
   - The Zed extension consumes the parser/queries for syntax highlighting, indentation, and outline extraction.
   - The LSP server provides diagnostics back to the editor, likely using the same language rules or parser-derived checks.

8. **Build and packaging boundaries**
   - `tree-sitter-hyperql/` is built with the standard Tree-sitter toolchain and supports multiple package managers/build systems (`Cargo`, `npm`, `pip`, `Go`, `Maven`, `Zig`, `CMake`, `Makefile`).
   - `hyperql-lsp/` is built with Zig (`build.zig`), while `hyperql-zed/` is a Rust extension package (`Cargo.toml`, `extension.toml`).
   - This repo therefore has three distinct packaging targets: parser library, editor extension, and LSP binary.

9. **Setup and developer workflow**
   - `setup.sh` and `setup.ps1` automate local development setup, especially building the LSP and wiring the Zed extension to local paths.
   - `uninstall.sh` and `uninstall.ps1` reverse that local installation.
   - The README’s build steps show the parser must be built separately before editor integration works.

10. **Quality, compliance, and release hygiene**
   - `.github/workflows/license-check.yml`, `deny.toml`, and `THIRD_PARTY_LICENSES.md` indicate dependency/license governance.
   - This matters because the repository distributes generated parser code and bindings across ecosystems, so license compliance is part of the release boundary.

11. **What an architecture diagram should show**
   - Put the **Tree-sitter grammar** in the center as the shared syntax engine.
   - Draw inbound arrows from the **language specification/examples** into the grammar.
   - Draw outbound arrows from the grammar to **generated parser artifacts**, **language bindings**, and the **Zed extension queries**.
   - Show the **Zig LSP server** as a parallel consumer/validator that returns diagnostics to the editor.
   - Keep the **Zed extension** and **LSP server** separate, since they are packaged and built independently even though both serve editor integration.

Main entry points: [`tree-sitter-hyperql/grammar.js`](https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/grammar.js) (Grammar), [`tree-sitter-hyperql/package.json`](https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/package.json) (Parser pkg), [`tree-sitter-hyperql/bindings`](https://github.com/jarbear82/hyperql/tree/main/tree-sitter-hyperql/bindings) (Bindings), [`hyperql-zed/Cargo.toml`](https://github.com/jarbear82/hyperql/blob/main/hyperql-zed/Cargo.toml) (Zed extension)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_spec["Language Spec"]
  node_spec_root["Spec docs<br/>reference corpus"]
  node_spec_examples["Examples<br/>sample queries"]
  node_spec_ideas["Proposals<br/>design notes"]
end

subgraph group_parser["Parser Core"]
  node_grammar_src["Grammar<br/>[grammar.js]"]
  node_parser_gen["Parser C<br/>generated parser<br/>[parser.c]"]
  node_parser_meta["Node types<br/>parse metadata<br/>[grammar.json]"]
  node_parser_bindings["Bindings<br/>multi-language adapters"]
  node_parser_queries["Queries"]
  node_parser_pkg["Parser pkg<br/>publishable package<br/>[package.json]"]
end

subgraph group_editor["Editor Integration"]
  node_zed_ext["Zed extension<br/>rust extension<br/>[Cargo.toml]"]
  node_zed_lang["Zed config<br/>editor config<br/>[config.toml]"]
  node_lsp_server["LSP server<br/>zig service<br/>[main.zig]"]
end

subgraph group_ops["Tooling"]
  node_setup["Setup scripts<br/>local bootstrap<br/>[setup.sh]"]
  node_governance["License checks<br/>release governance<br/>[deny.toml]"]
end

node_spec_root -->|"defines"| node_grammar_src
node_spec_examples -->|"exercises"| node_grammar_src
node_spec_ideas -->|"proposes"| node_grammar_src
node_grammar_src -->|"generates"| node_parser_gen
node_grammar_src -->|"derives"| node_parser_meta
node_grammar_src -->|"shared by"| node_parser_bindings
node_parser_gen -->|"embedded in"| node_parser_bindings
node_parser_pkg -->|"packages"| node_parser_bindings
node_parser_queries -->|"consumed by"| node_zed_lang
node_parser_bindings -->|"parses for"| node_zed_ext
node_parser_pkg -->|"supplies"| node_zed_ext
node_parser_pkg -->|"supports"| node_lsp_server
node_zed_ext -.->|"pairs with"| node_lsp_server
node_setup -->|"wires"| node_zed_ext
node_setup -->|"builds"| node_lsp_server
node_governance -->|"governs"| node_parser_pkg

click node_spec_root "https://github.com/jarbear82/hyperql/tree/main/hyperql-language-specification"
click node_spec_examples "https://github.com/jarbear82/hyperql/tree/main/hyperql-language-specification/Example_HQL_Files"
click node_spec_ideas "https://github.com/jarbear82/hyperql/tree/main/hyperql-language-specification/Ideas"
click node_grammar_src "https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/grammar.js"
click node_parser_gen "https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/src/parser.c"
click node_parser_meta "https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/src/grammar.json"
click node_parser_bindings "https://github.com/jarbear82/hyperql/tree/main/tree-sitter-hyperql/bindings"
click node_parser_queries "https://github.com/jarbear82/hyperql/tree/main/tree-sitter-hyperql/queries"
click node_parser_pkg "https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/package.json"
click node_zed_ext "https://github.com/jarbear82/hyperql/blob/main/hyperql-zed/Cargo.toml"
click node_zed_lang "https://github.com/jarbear82/hyperql/blob/main/hyperql-zed/languages/hyperql/config.toml"
click node_lsp_server "https://github.com/jarbear82/hyperql/blob/main/hyperql-lsp/src/main.zig"
click node_setup "https://github.com/jarbear82/hyperql/blob/main/setup.sh"
click node_governance "https://github.com/jarbear82/hyperql/blob/main/deny.toml"

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_spec_root,node_spec_examples,node_spec_ideas toneBlue
class node_grammar_src,node_parser_gen,node_parser_meta,node_parser_bindings,node_parser_queries,node_parser_pkg toneAmber
class node_zed_ext,node_zed_lang,node_lsp_server toneMint
class node_setup,node_governance toneRose
```

## Components

### Language Spec

Versioned HyperQL reference material and examples.

- [Spec docs](https://github.com/jarbear82/hyperql/tree/main/hyperql-language-specification): reference corpus · Versioned language specification JSON plus human-readable proposals and review notes. · `hyperql-language-specification`
- [Examples](https://github.com/jarbear82/hyperql/tree/main/hyperql-language-specification/Example_HQL_Files): sample queries · Example .hql and .hyperql files used as reference inputs for language behavior. · `hyperql-language-specification/Example_HQL_Files`
- [Proposals](https://github.com/jarbear82/hyperql/tree/main/hyperql-language-specification/Ideas): design notes · Ideas and proposal documents that shape future language evolution. · `hyperql-language-specification/Ideas`

### Parser Core

Tree-sitter grammar, generated artifacts, and bindings.

- [Grammar](https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/grammar.js): tree-sitter grammar · Core HyperQL syntax definition that drives parse generation. · `tree-sitter-hyperql/grammar.js`
- [Parser C](https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/src/parser.c): generated parser · Generated Tree-sitter parser implementation and core parse tables. · `tree-sitter-hyperql/src/parser.c`
- [Node types](https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/src/grammar.json): parse metadata · Generated grammar metadata consumed by bindings and tooling. · `tree-sitter-hyperql/src/grammar.json`
- [Bindings](https://github.com/jarbear82/hyperql/tree/main/tree-sitter-hyperql/bindings): multi-language adapters · C, Go, Java, Node.js, Python, Rust, and Zig bindings for embedding the parser. · `tree-sitter-hyperql/bindings`
- [Queries](https://github.com/jarbear82/hyperql/tree/main/tree-sitter-hyperql/queries): editor queries · Shared Tree-sitter queries for highlighting, indentation, and outline extraction. · `tree-sitter-hyperql/queries`
- [Parser pkg](https://github.com/jarbear82/hyperql/blob/main/tree-sitter-hyperql/package.json): publishable package · Tree-sitter package boundary and build metadata for distribution across ecosystems. · `tree-sitter-hyperql/package.json`

### Editor Integration

Zed extension and LSP runtime layers.

- [Zed extension](https://github.com/jarbear82/hyperql/blob/main/hyperql-zed/Cargo.toml): rust extension · Zed integration package that ships the HyperQL grammar artifact and editor configuration. · `hyperql-zed/Cargo.toml`
- [Zed config](https://github.com/jarbear82/hyperql/blob/main/hyperql-zed/languages/hyperql/config.toml): editor config · Language configuration and Tree-sitter query files used by Zed. · `hyperql-zed/languages/hyperql/config.toml`
- [LSP server](https://github.com/jarbear82/hyperql/blob/main/hyperql-lsp/src/main.zig): zig service · Zig-based language server that provides diagnostics and editor feedback. · `hyperql-lsp/src/main.zig`

### Tooling

Setup and release-governance boundaries.

- [Setup scripts](https://github.com/jarbear82/hyperql/blob/main/setup.sh): local bootstrap · Helper scripts for wiring local builds and editor integration. · `setup.sh`
- [License checks](https://github.com/jarbear82/hyperql/blob/main/deny.toml): release governance · Dependency and license compliance boundaries for generated code and packaged artifacts. · `deny.toml`

## Connections

- Spec docs → Grammar: defines · Language editions and reference material inform grammar evolution.
- Examples → Grammar: exercises · Example queries provide coverage for syntax behavior.
- Proposals → Grammar: proposes · Design proposals feed future grammar changes.
- Grammar → Parser C: generates · Tree-sitter compiles the grammar into parser artifacts.
- Grammar → Node types: derives · The grammar defines node types and parse structure metadata.
- Grammar → Bindings: shared by · Bindings expose the same parser core to multiple host languages.
- Parser C → Bindings: embedded in · Generated parser code is consumed by the language bindings.
- Parser pkg → Bindings: packages · The parser package boundary distributes bindings and build targets.
- Queries → Zed config: consumed by · Zed uses Tree-sitter queries for highlighting, indentation, and outline.
- Bindings → Zed extension: parses for · The editor extension relies on the parser through generated grammar assets.
- Parser pkg → Zed extension: supplies · The extension package ships the compiled grammar artifact and integration glue.
- Parser pkg → LSP server: supports · The language server depends on parser behavior for validation and diagnostics.
- Zed extension → LSP server: pairs with · The editor extension and language server are separate integration layers.
- Setup scripts → Zed extension: wires · Bootstrap scripts configure local paths for Zed development.
- Setup scripts → LSP server: builds · Bootstrap scripts help compile and install the Zig LSP server.
- License checks → Parser pkg: governs · License checks cover the distributed parser package and generated artifacts.
