# godunko/adawebpack architecture

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

- Interactive diagram: https://gitdiagram.com/godunko/adawebpack
- Repository: https://github.com/godunko/adawebpack

## Overview

#### Purpose and entry points
AdaWebPack is an Ada-to-WebAssembly toolchain distribution: a GNAT-LLVM WebAssembly target, a tailored Ada runtime, and Ada bindings to browser Web APIs. Build orchestration starts from `Makefile` and the GNAT project definitions `gnat/adawebpack.gpr` and `gnat/adawebpack_config.gpr`. Consumer-facing validation/demo entry points are the browser examples under `examples/`.

#### Toolchain integration layer
The repository does not implement a standalone compiler; it adapts external GNAT-LLVM/GCC/bb-runtimes sources to produce a wasm target. Patches alter upstream compiler/interface behavior, while the target makefile is linked into GNAT-LLVM’s build tree:
- `patches/gnat-llvm.patch`
- `patches/llvm_wrapper2.patch`
- `source/rtl/Makefile.target`

The resulting compiler depends on LLVM/Clang plus `wasm-ld`/LLD with the WebAssembly target enabled.

#### WebAssembly Ada runtime
A minimal/ported GNAT runtime supplies initialization, exceptions, memory, string/character conversion, stack handling, and target parameters for wasm32. This is the execution boundary between generated Ada code and the Wasm environment. Important restrictions follow from this runtime/toolchain model: no nested subprograms, tasking, or protected objects; exception support is limited.
- `source/rtl/wasm32.atp`
- `source/rtl/s-init.adb`
- `source/rtl/a-except.adb`

#### JavaScript/Wasm interop substrate
Core `Wasm` packages model JavaScript objects, constructors, methods, attributes, strings, console output, and controlled abort behavior. Ada bindings use this substrate to invoke browser-provided objects and APIs rather than embedding browser implementations.
- `source/wasm.ads`
- `source/wasm-objects.adb`
- `source/wasm-strings.adb`

#### Browser API binding layers
Bindings are organized by Web platform domain and build upward from generic DOM types to specialized APIs. The principal flow is Ada application code → typed Ada Web binding → Wasm/JavaScript interop → browser API.
- DOM/BOM: `source/dom/web-dom.ads`, `source/bom/web-window.ads`
- HTML elements: `source/html/web-html-elements.ads`, `source/html/web-html-documents.adb`
- Event model: `source/ui_events/web-ui_events.ads`, `source/dom/web-dom-events.adb`

#### Network, URL, and graphics integrations
Separate bindings expose browser-managed asynchronous/platform services, maintaining browser APIs as the external-service boundary:
- WebSocket/message events: `source/sockets/web-sockets.adb`, `source/sockets/web-message_events.ads`
- XMLHttpRequest: `source/xhr/web-xhr-requests.adb`
- URL/query parameters: `source/url/web-url-url_search_params.adb`
- WebGL rendering contexts and resources: `source/webgl/web-gl-rendering_contexts.adb`, `source/webgl/web-gl.ads`

#### Example delivery model
Examples compile Ada application units to Wasm and pair them with static HTML pages loaded by a browser over HTTP. They demonstrate DOM callbacks, Ada-callable behavior, and WebGL; the browser and an HTTP server are required deployment/runtime infrastructure.
- `examples/call_ada/main.adb`, `examples/call_ada/index.html`
- `examples/toggle_hidden/main.adb`, `examples/toggle_hidden/index.html`
- `examples/webgl_basic/main.adb`, `examples/webgl_basic/index.html`

Main entry points: [`source/wasm.ads`](https://github.com/godunko/adawebpack/blob/master/source/wasm.ads) (Wasm interop substrate), [`examples/call_ada/main.adb`](https://github.com/godunko/adawebpack/blob/master/examples/call_ada/main.adb) (Ada example applications), [`source/dom/web-dom.ads`](https://github.com/godunko/adawebpack/blob/master/source/dom/web-dom.ads) (DOM and BOM), [`source/rtl/s-init.adb`](https://github.com/godunko/adawebpack/blob/master/source/rtl/s-init.adb) (Ported GNAT runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Toolchain Build"]
  node_orchestration["Build orchestration<br/>Make/GNAT projects"]
  node_gnat_project["AdaWebPack project<br/>GNAT project<br/>[adawebpack.gpr]"]
  node_upstream_patches["GNAT-LLVM patches<br/>upstream adaptation<br/>[gnat-llvm.patch]"]
  node_target_makefile["Wasm target makefile<br/>GNAT target build<br/>[Makefile.target]"]
  node_external_toolchain{{"GNAT-LLVM + LLVM/LLD<br/>external toolchain"}}
end

subgraph group_runtime["Wasm Runtime &amp; Interop"]
  node_wasm_runtime["Ported GNAT runtime<br/>wasm32 runtime<br/>[s-init.adb]"]
  node_target_parameters["Wasm target parameters<br/>runtime target config<br/>[wasm32.atp]"]
  node_wasm_interop["Wasm interop substrate<br/>Ada JS interop<br/>[wasm.ads]"]
  node_js_object_layer["JS objects and strings<br/>interop implementation<br/>[wasm-objects.adb]"]
end

subgraph group_bindings["Browser Bindings"]
  node_dom_bom["DOM and BOM<br/>browser bindings<br/>[web-dom.ads]"]
  node_html_bindings["HTML bindings<br/>browser bindings"]
  node_event_bindings["UI event bindings<br/>browser bindings<br/>[web-ui_events.ads]"]
  node_network_bindings["Network bindings<br/>browser bindings<br/>[web-sockets.adb]"]
  node_url_bindings["URL bindings<br/>browser bindings"]
  node_webgl_bindings["WebGL bindings<br/>browser bindings"]
  node_browser{{"Browser Web APIs<br/>external runtime"}}
end

subgraph group_examples["Examples &amp; Deployment"]
  node_ada_examples["Ada example applications<br/>Ada applications<br/>[main.adb]"]
  node_static_pages["Example HTML pages<br/>static web assets<br/>[index.html]"]
  node_http_server{{"HTTP server<br/>deployment infrastructure"}}
end

node_orchestration -->|"uses"| node_gnat_project
node_orchestration -->|"builds target"| node_target_makefile
node_upstream_patches -->|"adapts"| node_external_toolchain
node_target_makefile -->|"integrates with"| node_external_toolchain
node_external_toolchain -->|"builds with"| node_wasm_runtime
node_target_parameters -->|"configures"| node_wasm_runtime
node_js_object_layer -->|"implements"| node_wasm_interop
node_dom_bom -->|"uses"| node_wasm_interop
node_html_bindings -->|"specializes"| node_dom_bom
node_event_bindings -->|"extends"| node_dom_bom
node_network_bindings -->|"uses"| node_wasm_interop
node_url_bindings -->|"uses"| node_wasm_interop
node_webgl_bindings -->|"uses"| node_wasm_interop
node_wasm_interop -->|"invokes"| node_browser
node_ada_examples -->|"compiled by"| node_gnat_project
node_ada_examples -->|"runs on"| node_wasm_runtime
node_ada_examples -->|"uses bindings"| node_dom_bom
node_ada_examples -->|"uses for graphics"| node_webgl_bindings
node_static_pages -->|"served by"| node_http_server
node_http_server -->|"delivers pages and Wasm"| node_browser
node_browser -->|"loads and executes"| node_ada_examples

click node_orchestration "https://github.com/godunko/adawebpack/blob/master/Makefile"
click node_gnat_project "https://github.com/godunko/adawebpack/blob/master/gnat/adawebpack.gpr"
click node_upstream_patches "https://github.com/godunko/adawebpack/blob/master/patches/gnat-llvm.patch"
click node_target_makefile "https://github.com/godunko/adawebpack/blob/master/source/rtl/Makefile.target"
click node_wasm_runtime "https://github.com/godunko/adawebpack/blob/master/source/rtl/s-init.adb"
click node_target_parameters "https://github.com/godunko/adawebpack/blob/master/source/rtl/wasm32.atp"
click node_wasm_interop "https://github.com/godunko/adawebpack/blob/master/source/wasm.ads"
click node_js_object_layer "https://github.com/godunko/adawebpack/blob/master/source/wasm-objects.adb"
click node_dom_bom "https://github.com/godunko/adawebpack/blob/master/source/dom/web-dom.ads"
click node_html_bindings "https://github.com/godunko/adawebpack/blob/master/source/html/web-html-elements.ads"
click node_event_bindings "https://github.com/godunko/adawebpack/blob/master/source/ui_events/web-ui_events.ads"
click node_network_bindings "https://github.com/godunko/adawebpack/blob/master/source/sockets/web-sockets.adb"
click node_url_bindings "https://github.com/godunko/adawebpack/blob/master/source/url/web-url-url_search_params.adb"
click node_webgl_bindings "https://github.com/godunko/adawebpack/blob/master/source/webgl/web-gl-rendering_contexts.adb"
click node_ada_examples "https://github.com/godunko/adawebpack/blob/master/examples/call_ada/main.adb"
click node_static_pages "https://github.com/godunko/adawebpack/blob/master/examples/call_ada/index.html"

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_orchestration,node_gnat_project,node_upstream_patches,node_target_makefile,node_external_toolchain toneBlue
class node_wasm_runtime,node_target_parameters,node_wasm_interop,node_js_object_layer toneAmber
class node_dom_bom,node_html_bindings,node_event_bindings,node_network_bindings,node_url_bindings,node_webgl_bindings,node_browser toneMint
class node_ada_examples,node_static_pages,node_http_server toneRose
```

## Components

### Toolchain Build

- [Build orchestration](https://github.com/godunko/adawebpack/blob/master/Makefile): Make/GNAT projects · Coordinates target and consumer builds. · `Makefile`
- [AdaWebPack project](https://github.com/godunko/adawebpack/blob/master/gnat/adawebpack.gpr): GNAT project · `gnat/adawebpack.gpr`
- [GNAT-LLVM patches](https://github.com/godunko/adawebpack/blob/master/patches/gnat-llvm.patch): upstream adaptation · Adapts external compiler and interface behavior. · `patches/gnat-llvm.patch`
- [Wasm target makefile](https://github.com/godunko/adawebpack/blob/master/source/rtl/Makefile.target): GNAT target build · Linked into the GNAT-LLVM build tree. · `source/rtl/Makefile.target`
- **GNAT-LLVM + LLVM/LLD**: external toolchain · Produces WebAssembly-targeted Ada output.

### Wasm Runtime & Interop

- [Ported GNAT runtime](https://github.com/godunko/adawebpack/blob/master/source/rtl/s-init.adb): wasm32 runtime · Initialization, exceptions, memory, stack, and target support. · `source/rtl/s-init.adb`
- [Wasm target parameters](https://github.com/godunko/adawebpack/blob/master/source/rtl/wasm32.atp): runtime target config · `source/rtl/wasm32.atp`
- [Wasm interop substrate](https://github.com/godunko/adawebpack/blob/master/source/wasm.ads): Ada JS interop · Models JavaScript objects, methods, attributes, and console access. · `source/wasm.ads`
- [JS objects and strings](https://github.com/godunko/adawebpack/blob/master/source/wasm-objects.adb): interop implementation · `source/wasm-objects.adb`

### Browser Bindings

- [DOM and BOM](https://github.com/godunko/adawebpack/blob/master/source/dom/web-dom.ads): browser bindings · Generic DOM types and window access. · `source/dom/web-dom.ads`
- [HTML bindings](https://github.com/godunko/adawebpack/blob/master/source/html/web-html-elements.ads): browser bindings · `source/html/web-html-elements.ads`
- [UI event bindings](https://github.com/godunko/adawebpack/blob/master/source/ui_events/web-ui_events.ads): browser bindings · `source/ui_events/web-ui_events.ads`
- [Network bindings](https://github.com/godunko/adawebpack/blob/master/source/sockets/web-sockets.adb): browser bindings · WebSocket, message-event, and XMLHttpRequest APIs. · `source/sockets/web-sockets.adb`
- [URL bindings](https://github.com/godunko/adawebpack/blob/master/source/url/web-url-url_search_params.adb): browser bindings · `source/url/web-url-url_search_params.adb`
- [WebGL bindings](https://github.com/godunko/adawebpack/blob/master/source/webgl/web-gl-rendering_contexts.adb): browser bindings · Rendering contexts and resources. · `source/webgl/web-gl-rendering_contexts.adb`
- **Browser Web APIs**: external runtime · Provides DOM, platform services, and WebGL.

### Examples & Deployment

- [Ada example applications](https://github.com/godunko/adawebpack/blob/master/examples/call_ada/main.adb): Ada applications · DOM callbacks, Ada-callable behavior, and WebGL demos. · `examples/call_ada/main.adb`
- [Example HTML pages](https://github.com/godunko/adawebpack/blob/master/examples/call_ada/index.html): static web assets · `examples/call_ada/index.html`
- **HTTP server**: deployment infrastructure · Serves example pages and Wasm to the browser.

## Connections

- Build orchestration → AdaWebPack project: uses
- Build orchestration → Wasm target makefile: builds target
- GNAT-LLVM patches → GNAT-LLVM + LLVM/LLD: adapts
- Wasm target makefile → GNAT-LLVM + LLVM/LLD: integrates with
- GNAT-LLVM + LLVM/LLD → Ported GNAT runtime: builds with
- Wasm target parameters → Ported GNAT runtime: configures
- JS objects and strings → Wasm interop substrate: implements
- DOM and BOM → Wasm interop substrate: uses
- HTML bindings → DOM and BOM: specializes
- UI event bindings → DOM and BOM: extends
- Network bindings → Wasm interop substrate: uses
- URL bindings → Wasm interop substrate: uses
- WebGL bindings → Wasm interop substrate: uses
- Wasm interop substrate → Browser Web APIs: invokes
- Ada example applications → AdaWebPack project: compiled by
- Ada example applications → Ported GNAT runtime: runs on
- Ada example applications → DOM and BOM: uses bindings
- Ada example applications → WebGL bindings: uses for graphics
- Example HTML pages → HTTP server: served by
- HTTP server → Browser Web APIs: delivers pages and Wasm
- Browser Web APIs → Ada example applications: loads and executes