Gui Architecture

Axon GUI Architecture

Cross-platform GUI framework for the Axon programming language.

Version: Draft — Pre-implementation
Status: Planning (M9-M12)
Target: macOS (primary), Linux, Windows

---

Vision

Axon apps are fully compiled native binaries that run on any OS with the Axon runtime installed. The GUI framework ships as part of the Axon distribution — no external dependencies required at deploy time.

Developer writes Axon code → axonc compiles → native binary
User has Axon runtime installed → runs the app

Architecture Overview

┌─────────────────────────────────────────────────┐
│                 Axon Application                │
│  (pure Axon code — business logic + UI)         │
├─────────────────────────────────────────────────┤
│              axon.ui Module (Axon)              │
│  Widgets, layout helpers, theme API             │
├─────────────────────────────────────────────────┤
│           UI Framework (C: libaxon_ui)          │
│  Layout engine, event dispatch, widget state    │
├─────────────────────────────────────────────────┤
│         Rendering Engine (C: libaxon_render)    │
│  Software rasterizer, text, images              │
│  GPU backends: Metal (macOS), Vulkan (Linux/Win)│
├──────────┬──────────────┬───────────────────────┤
│  macOS   │    Linux     │      Windows          │
│  AppKit  │  X11/Wayland │      Win32            │
│  (ObjC   │  (Xlib/      │    (CreateWindow,     │
│  runtime)│  libwayland)  │     WndProc)          │
└──────────┴──────────────┴───────────────────────┘
         Platform Abstraction Layer (C: libaxon_pal)

Design Decisions

1. C Runtime + Axon API

The platform-specific code is written in C (and Objective-C for macOS). Axon programs call into it via extern declarations. This means:

• Zero Objective-C/Win32/X11 knowledge needed for Axon developers
• Battle-tested C interop — no new FFI mechanisms required
• Ships with Axon — libaxon_pal and libaxon_render are part of the distribution

2. Software Rendering First

The initial renderer is a CPU-based 2D rasterizer — no GPU required. This ensures:

• Works everywhere (SSH, CI, headless, old hardware)
• Simpler implementation and debugging
• GPU backends (Metal, Vulkan) added later for performance

3. Immediate-Mode UI (MVP)

The first UI framework is immediate-mode (like Dear ImGui/Nuklear):

;; Every frame, describe the UI
(if (ui.button ctx "Click Me")
  (set count (add count (i64 1))))
(ui.label ctx (fmt "Count: {}" count))

Why immediate-mode first:

• Fewer language features needed (no closures for callbacks)
• State lives in user code, not framework
• Simpler to implement and debug
• Good enough for tools, dashboards, and many apps

Future: Declarative mode (like SwiftUI) once Axon has closures and generics.

4. Flexbox Layout

Layout uses a flexbox-like algorithm — the same model used by CSS, React Native, and Flutter. Well-understood, well-tested, handles 95% of UI layouts.

Platform Details

macOS (Primary Target)

Uses the Objective-C runtime C API — no Objective-C compiler required:

// Create an NSWindow from pure C
id window = ((id(*)(id,SEL,CGRect,int,int,int))objc_msgSend)(
    ((id(*)(id,SEL))objc_msgSend)((id)objc_getClass("NSWindow"),
     sel_registerName("alloc")),
    sel_registerName("initWithContentRect:styleMask:backing:defer:"),
    frame, 15, 2, 0);

Key runtime functions: objc_msgSend, objc_getClass, sel_registerName, class_addMethod.

Link flags: -framework Cocoa

Linux

Two backends:

• X11 (via Xlib) — widest compatibility, simpler API
• Wayland (via libwayland) — modern compositors, more complex

Framebuffer via MIT-SHM (X11) or wl_shm (Wayland) for zero-copy pixel blitting.

Link flags: -lX11 -lXext

Windows

Uses Win32 API: CreateWindowEx, GetMessage/DispatchMessage loop, GDI for framebuffer.

Link flags: -lgdi32 -luser32 -lkernel32

Language Prerequisites

The GUI framework requires these language features (planned for M2-M5):

Feature	Milestone	Why Needed
Function pointers	M2	Event callbacks
Enums	M2	Event types, widget states
Pattern matching	M2	Event dispatch
Generics	M2	Type-safe containers
Result types	M3	Fallible operations
Multi-file modules	M4	Code organization
Heap allocation	M5	Widget trees, buffers
String type	M5	Text everywhere
Dynamic arrays	M5	Widget children
Hash maps	M5	Widget lookup, styles

Milestones

Milestone	Focus	Key Deliverable
M9	Platform Layer	libaxon_pal — windows, events, framebuffer
M10	Rendering	libaxon_render — shapes, text, images
M11	UI Framework	Layout, widgets, themes, axon.ui API
M12	Polish	Full widgets, app bundling, tooling

Future Directions

• Declarative UI — SwiftUI-like syntax with closures and reactive state
• Custom UI DSL — .axui files compiled alongside .axs code
• WebAssembly target — Run Axon GUI apps in browsers
• Mobile — iOS (UIKit) and Android (NDK) backends
• 3D rendering — Scene graph, shaders, game engine integration