# codurralabs/nebulara architecture

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

- Interactive diagram: https://gitdiagram.com/codurralabs/nebulara
- Repository: https://github.com/codurralabs/nebulara

## Overview

1. **What this repo is**
   Nebulara is a language platform, not a single app: it contains the language grammar, compiler pipeline, native runtime/JIT, a VM layer, standard libraries, and a few higher-level domain modules. The core architectural boundary is between **NBS source modules** (`.nbs`) and the **native/runtime execution stack** implemented in C and JavaScript.

2. **Language front end**
   The front end lives in `Grammar/` and `Parser/`. `Grammar/grammar.nbs` and `Grammar/enhanced-grammar.nbs` define the language shape, while `Parser/lexer-core.nbs`, `Parser/lexer.nbs`, `Parser/parser-core.nbs` turn source into structured program data. This is the first major flow: **source text → tokens → parsed syntax tree / intermediate form**.

3. **Compiler pipeline**
   `Compiler/` contains the transformation stages: `semantic.nbs` for validation and resolution, `ir-ssa.nbs` for intermediate representation, `transpiler.nbs` plus `transpiler-js.nbs` and `transpiler-py.nbs` for target emission, and `binary-emitter.nbs` / `x86-binary.nbs` for machine-code output. `Compiler/bootcompiler.nbs` and `Compiler/nbs-bootstrap.c` indicate a bootstrap path for compiling the compiler itself.

4. **Code generation targets**
   The compiler is multi-target. One path produces native x86 output for the in-repo JIT/runtime, and other paths emit JavaScript or Python. That means the architecture is split between a **native backend** and **source-to-source transpilers**, with shared front-end semantics feeding both.

5. **Runtime and native execution**
   `Runtime/` is the execution boundary. `nbs_cli.c`, `nbs_jit.c`, `nbs_loader.c`, and `nbs_x64.c` handle command-line execution, JIT compilation, and module loading. `Runtime/nbs_loader.h` is the shared interface, and `Runtime/node_loader.js` provides a Node-based loader path. In the current repo state, the readme says the **32-bit x86 JIT is working** while x64 is incomplete.

6. **Virtual machine layer**
   `VM/bootstrap.nbs`, `VM/nrunner.nbs`, and `VM/nvm-vm.nbs` form a VM-oriented execution model separate from the native JIT. The architecture therefore has two execution abstractions: a **native JIT/runtime path** and a **VM/bootstrap path** for module execution and experimentation.

7. **Standard library and core services**
   `std/` provides language-level primitives and utility modules: collections, JSON, network, time, strings, primitives, and kanban. `Lib/` adds lower-level integration and math/IO helpers, plus FFI and adapter layers. This is the boundary where language code gets access to **common runtime services** without embedding those concerns in the compiler.

8. **Foreign-function and host adapters**
   The C adapters in `Lib/` (`cpp-adapter.c`, `nodejs-adapter.c`, `python-adapter.c`) plus NBS-side FFI modules (`Lib/ffi.nbs`, `Lib/nadapter.nbs`, `transport/ffi.nbs`) define host interoperability. `Lib/vulkan.nbs` and `Lib/nvulkan.nbs` show planned or partial GPU integration. Architecturally, this is the **escape hatch** from Nebulara into native libraries and external runtimes.

9. **Transport and IPC**
   `transport/ipc.nbs` and `transport/ffi.nbs` separate inter-process communication from in-process FFI. That implies a runtime boundary between local module calls and cross-process integration, likely used by loaders, orchestrators, or host tooling.

10. **Higher-level application layer**
   `aurora/` and `knowledge/` are not core language infrastructure; they look like an AI/knowledge application layer built on top of Nebulara. `aurora/events.nbs`, `aurora/gateway.nbs`, and `aurora/orchestrator.nbs` suggest event-driven orchestration, while `knowledge/store.nbs` suggests an embedded knowledge store. These modules sit above the compiler/runtime stack and consume the language as a platform.

11. **Packages and configuration**
   `Packages/BUILD.nbs` and `Packages/config.nbs` indicate a package/build abstraction inside the ecosystem. Combined with `configure`, `configure.nbs`, `build.nbs`, `Makefile`, and `build.bat`, the repo supports multiple build entrypoints and bootstrap modes, with the native toolchain currently centered on MinGW-w64 per the readme.

12. **Verification, release, and legacy surface**
   Tests are split between `test/hello.nbs` and `tests/nebulara.test.ts`, showing both language-level and host-level validation. GitHub workflows handle release and SLSA publishing. `v1/` is a legacy packaging surface, while `docs/`, `SPEC.md`, and `ARCHITECTURE.md` are the design contract for the system.

Main entry points: [`std/collections.nbs`](https://github.com/codurralabs/nebulara/blob/main/std/collections.nbs) (Std lib), [`Compiler/ir-ssa.nbs`](https://github.com/codurralabs/nebulara/blob/main/Compiler/ir-ssa.nbs) (IR SSA), [`Runtime/nbs_loader.c`](https://github.com/codurralabs/nebulara/blob/main/Runtime/nbs_loader.c) (Loader), [`Lib/ffi.nbs`](https://github.com/codurralabs/nebulara/blob/main/Lib/ffi.nbs) (FFI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Language front end"]
  node_grammar["Grammar<br/>[grammar.nbs]"]
  node_parser["Parser<br/>lex/parse<br/>[parser-core.nbs]"]
end

subgraph group_compiler["Compiler pipeline"]
  node_semantic["Semantic<br/>analysis<br/>[semantic.nbs]"]
  node_ir["IR SSA<br/>intermediate rep<br/>[ir-ssa.nbs]"]
  node_transpiler["Transpilers<br/>multi-target emit<br/>[transpiler.nbs]"]
  node_native_emit["Native emit<br/>x86 backend<br/>[binary-emitter.nbs]"]
  node_bootstrap["Bootstrap<br/>self-hosting<br/>[bootcompiler.nbs]"]
end

subgraph group_runtime["Execution stack"]
  node_cli["CLI<br/>runtime entry<br/>[nbs_cli.c]"]
  node_loader["Loader<br/>[nbs_loader.c]"]
  node_jit["JIT<br/>native runtime<br/>[nbs_jit.c]"]
  node_vm["VM<br/>[nvm-vm.nbs]"]
  node_builtins["Builtins<br/>runtime core<br/>[builtins.nbs]"]
end

subgraph group_stdlib["Libraries and interop"]
  node_stdlib["Std lib<br/>core library<br/>[collections.nbs]"]
  node_ffi["FFI<br/>interop<br/>[ffi.nbs]"]
  node_adapters["Adapters<br/>host bridges<br/>[nodejs-adapter.c]"]
  node_transport["Transport<br/>ipc/ffi<br/>[ipc.nbs]"]
end

subgraph group_apps["Higher layers"]
  node_aurora["Aurora<br/>app module<br/>[orchestrator.nbs]"]
  node_knowledge["Knowledge<br/>app module<br/>[store.nbs]"]
end

node_grammar -->|"defines syntax"| node_parser
node_parser -->|"AST / IR"| node_semantic
node_semantic -->|"lowering"| node_ir
node_ir -->|"emit source"| node_transpiler
node_ir -->|"emit native"| node_native_emit
node_bootstrap -->|"bootstraps"| node_native_emit
node_native_emit -->|"feeds code"| node_jit
node_cli -->|"starts"| node_loader
node_loader -->|"exposes"| node_builtins
node_loader -->|"loads for"| node_jit
node_jit -.->|"alternative path"| node_vm
node_builtins -->|"supports"| node_stdlib
node_stdlib -->|"escapes to host"| node_ffi
node_ffi -->|"bridges"| node_adapters
node_ffi -.->|"cross-process"| node_transport
node_transport -->|"orchestrates"| node_aurora
node_transport -->|"persists"| node_knowledge
node_vm -.->|"runs modules"| node_aurora
node_stdlib -->|"uses"| node_aurora
node_stdlib -->|"uses"| node_knowledge

click node_grammar "https://github.com/codurralabs/nebulara/blob/main/Grammar/grammar.nbs"
click node_parser "https://github.com/codurralabs/nebulara/blob/main/Parser/parser-core.nbs"
click node_semantic "https://github.com/codurralabs/nebulara/blob/main/Compiler/semantic.nbs"
click node_ir "https://github.com/codurralabs/nebulara/blob/main/Compiler/ir-ssa.nbs"
click node_transpiler "https://github.com/codurralabs/nebulara/blob/main/Compiler/transpiler.nbs"
click node_native_emit "https://github.com/codurralabs/nebulara/blob/main/Compiler/binary-emitter.nbs"
click node_bootstrap "https://github.com/codurralabs/nebulara/blob/main/Compiler/bootcompiler.nbs"
click node_cli "https://github.com/codurralabs/nebulara/blob/main/Runtime/nbs_cli.c"
click node_loader "https://github.com/codurralabs/nebulara/blob/main/Runtime/nbs_loader.c"
click node_jit "https://github.com/codurralabs/nebulara/blob/main/Runtime/nbs_jit.c"
click node_vm "https://github.com/codurralabs/nebulara/blob/main/VM/nvm-vm.nbs"
click node_builtins "https://github.com/codurralabs/nebulara/blob/main/Runtime/builtins.nbs"
click node_stdlib "https://github.com/codurralabs/nebulara/blob/main/std/collections.nbs"
click node_ffi "https://github.com/codurralabs/nebulara/blob/main/Lib/ffi.nbs"
click node_adapters "https://github.com/codurralabs/nebulara/blob/main/Lib/nodejs-adapter.c"
click node_transport "https://github.com/codurralabs/nebulara/blob/main/transport/ipc.nbs"
click node_aurora "https://github.com/codurralabs/nebulara/blob/main/aurora/orchestrator.nbs"
click node_knowledge "https://github.com/codurralabs/nebulara/blob/main/knowledge/store.nbs"

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_grammar,node_parser toneBlue
class node_semantic,node_ir,node_transpiler,node_native_emit,node_bootstrap toneAmber
class node_cli,node_loader,node_jit,node_vm,node_builtins toneMint
class node_stdlib,node_ffi,node_adapters,node_transport toneRose
class node_aurora,node_knowledge toneIndigo
```

## Components

### Language front end

Grammar and parsing from source text into structured syntax.

- [Grammar](https://github.com/codurralabs/nebulara/blob/main/Grammar/grammar.nbs): language grammar · Defines Nebulara syntax and language shape. · `Grammar/grammar.nbs`
- [Parser](https://github.com/codurralabs/nebulara/blob/main/Parser/parser-core.nbs): lex/parse · Tokenizes and parses source into structured form. · `Parser/parser-core.nbs`

### Compiler pipeline

Semantic analysis, IR, transpilation, and native emission.

- [Semantic](https://github.com/codurralabs/nebulara/blob/main/Compiler/semantic.nbs): analysis · Validates and resolves program meaning before code generation. · `Compiler/semantic.nbs`
- [IR SSA](https://github.com/codurralabs/nebulara/blob/main/Compiler/ir-ssa.nbs): intermediate rep · Compiler intermediate representation and SSA-like lowering. · `Compiler/ir-ssa.nbs`
- [Transpilers](https://github.com/codurralabs/nebulara/blob/main/Compiler/transpiler.nbs): multi-target emit · Source-to-source emission for JavaScript and Python targets. · `Compiler/transpiler.nbs`
- [Native emit](https://github.com/codurralabs/nebulara/blob/main/Compiler/binary-emitter.nbs): x86 backend · Binary emission for native execution and JIT paths. · `Compiler/binary-emitter.nbs`
- [Bootstrap](https://github.com/codurralabs/nebulara/blob/main/Compiler/bootcompiler.nbs): self-hosting · Bootstrap compiler path and native bootstrap bridge. · `Compiler/bootcompiler.nbs`

### Execution stack

Native runtime, loader, JIT, and VM/bootstrap execution paths.

- [CLI](https://github.com/codurralabs/nebulara/blob/main/Runtime/nbs_cli.c): runtime entry · Command-line entry for launching Nebulara programs. · `Runtime/nbs_cli.c`
- [Loader](https://github.com/codurralabs/nebulara/blob/main/Runtime/nbs_loader.c): module loader · Loads modules and mediates runtime module access. · `Runtime/nbs_loader.c`
- [JIT](https://github.com/codurralabs/nebulara/blob/main/Runtime/nbs_jit.c): native runtime · Native execution and JIT compilation path. · `Runtime/nbs_jit.c`
- [VM](https://github.com/codurralabs/nebulara/blob/main/VM/nvm-vm.nbs): vm layer · VM/bootstrap execution model separate from native JIT. · `VM/nvm-vm.nbs`
- [Builtins](https://github.com/codurralabs/nebulara/blob/main/Runtime/builtins.nbs): runtime core · Core runtime builtins exposed to language code. · `Runtime/builtins.nbs`

### Libraries and interop

Standard library, FFI, host adapters, and transport boundaries.

- [Std lib](https://github.com/codurralabs/nebulara/blob/main/std/collections.nbs): core library · Collections, JSON, networking, strings, time, and primitives. · `std/collections.nbs`
- [FFI](https://github.com/codurralabs/nebulara/blob/main/Lib/ffi.nbs): interop · Foreign-function bridge into host libraries and adapters. · `Lib/ffi.nbs`
- [Adapters](https://github.com/codurralabs/nebulara/blob/main/Lib/nodejs-adapter.c): host bridges · C-side adapters for Node.js, Python, and native interop. · `Lib/nodejs-adapter.c`
- [Transport](https://github.com/codurralabs/nebulara/blob/main/transport/ipc.nbs): ipc/ffi · IPC and transport boundary separate from in-process calls. · `transport/ipc.nbs`

### Higher layers

Domain modules built on top of the language platform.

- [Aurora](https://github.com/codurralabs/nebulara/blob/main/aurora/orchestrator.nbs): app module · Event-driven orchestration layer built on the platform. · `aurora/orchestrator.nbs`
- [Knowledge](https://github.com/codurralabs/nebulara/blob/main/knowledge/store.nbs): app module · Higher-level knowledge store and domain persistence layer. · `knowledge/store.nbs`

## Connections

- Grammar → Parser: defines syntax · Grammar feeds the parsing pipeline.
- Parser → Semantic: AST / IR · Parsed structures move into semantic validation.
- Semantic → IR SSA: lowering · Validated programs are lowered into compiler IR.
- IR SSA → Transpilers: emit source · IR can be emitted to JavaScript and Python targets.
- IR SSA → Native emit: emit native · IR can be lowered to native binary output.
- Bootstrap → Native emit: bootstraps · Bootstrap path supports compiling compiler/runtime pieces.
- Native emit → JIT: feeds code · Native output is used by the runtime/JIT path.
- CLI → Loader: starts · CLI invokes module loading and runtime setup.
- Loader → Builtins: exposes · Loader wires builtin runtime services into execution.
- Loader → JIT: loads for · Loader prepares code for native execution.
- JIT → VM: alternative path · VM layer represents a separate execution model.
- Builtins → Std lib: supports · Builtins back standard library functionality.
- Std lib → FFI: escapes to host · Standard libraries can call into host interop.
- FFI → Adapters: bridges · FFI uses host-specific adapters and bindings.
- FFI → Transport: cross-process · Transport handles IPC-style integration boundaries.
- Transport → Aurora: orchestrates · Higher-level modules use transport for coordination.
- Transport → Knowledge: persists · Knowledge modules can be built on transport-backed services.
- VM → Aurora: runs modules · Aurora can execute through VM/bootstrap paths.
- Std lib → Aurora: uses · Application modules depend on standard library services.
- Std lib → Knowledge: uses · Knowledge layer relies on shared library services.