# gizclaw/gizos architecture

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

- Interactive diagram: https://gitdiagram.com/gizclaw/gizos
- Repository: https://github.com/gizclaw/gizos

## Overview

GizOS is a portable firmware and application platform spanning embedded devices, desktop, mobile, and WebAssembly. Its principal architecture flow is application code through the shared runtime and reusable libraries, then PAL contracts to platform providers and board/SDK integrations. The repository also contains distinct product branches for device management, scripting, games, and loader tooling. Relationships below follow the README’s documented layer model and visible source-index references; unsampled subsystem internals are represented conservatively.

Main entry points: [`libs/runtime`](https://github.com/gizclaw/gizos/tree/main/libs/runtime) (Application runtime), [`libs/pal/include/h2/pal`](https://github.com/gizclaw/gizos/tree/main/libs/pal/include/h2/pal) (PAL contracts), [`projects/h2loader/apps/loader/app/app.c`](https://github.com/gizclaw/gizos/blob/main/projects/h2loader/apps/loader/app/app.c) (H2Loader), [`projects/pixa_games/apps/dinodive/app/app.c`](https://github.com/gizclaw/gizos/blob/main/projects/pixa_games/apps/dinodive/app/app.c) (PIXA games)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Applications"]
  node_app_examples["Apps and examples"]
  node_h2loader["H2Loader<br/>[app.c]"]
  node_games["PIXA games<br/>[app.c]"]
  node_showcase["Showcase app<br/>[main.cpp]"]
end

subgraph group_core["Runtime and PAL"]
  node_runtime["Application runtime"]
  node_pal["PAL contracts"]
end

subgraph group_libs["Reusable Libraries"]
  node_game_runtime["Game runtime"]
  node_lua["Lua runtime<br/>[h2_lua.c]"]
  node_network_protocols["Networking and protocols"]
  node_audio_mixer["Audio mixer<br/>[h2_audio_mixer.c]"]
end

subgraph group_integrations["Platform Integrations"]
  node_desktop_support["Desktop support"]
  node_pal_providers["PAL providers"]
  node_native_components["Native components"]
  node_boards["Boards and SDKs"]
end

subgraph group_device["Device Services"]
  node_gizclaw["GizClaw client"]
  node_ble_config["BLE Wi-Fi setup"]
  node_loader_host["Loader host services"]
end

node_consumer(("Product developer"))

node_consumer -->|"composes"| node_app_examples
node_app_examples -->|"uses runtime"| node_runtime
node_h2loader -->|"uses runtime"| node_runtime
node_games -->|"uses game APIs"| node_game_runtime
node_games -->|"uses runtime"| node_runtime
node_showcase -->|"configures runtime"| node_runtime
node_runtime -->|"uses contracts"| node_pal
node_game_runtime -->|"uses audio and display"| node_pal
node_lua -->|"uses PAL services"| node_pal
node_ble_config -->|"uses runtime"| node_runtime
node_desktop_support -->|"provides runtime config"| node_runtime
node_showcase -->|"uses desktop support"| node_desktop_support
node_pal -->|"implemented by"| node_pal_providers
node_pal_providers -->|"integrates"| node_native_components
node_native_components -->|"targets boards"| node_boards
node_h2loader -.->|"uses loader services"| node_loader_host
node_gizclaw -.->|"uses PAL contracts"| node_pal
node_network_protocols -.->|"uses PAL networking"| node_pal
node_audio_mixer -.->|"uses audio"| node_pal

click node_app_examples "https://github.com/gizclaw/gizos/tree/main/projects"
click node_h2loader "https://github.com/gizclaw/gizos/blob/main/projects/h2loader/apps/loader/app/app.c"
click node_games "https://github.com/gizclaw/gizos/blob/main/projects/pixa_games/apps/dinodive/app/app.c"
click node_showcase "https://github.com/gizclaw/gizos/blob/main/projects/showcase/targets/cc_binary/showcase/main.cpp"
click node_runtime "https://github.com/gizclaw/gizos/tree/main/libs/runtime"
click node_pal "https://github.com/gizclaw/gizos/tree/main/libs/pal/include/h2/pal"
click node_game_runtime "https://github.com/gizclaw/gizos/blob/main/libs/game_runtime/src/h2_game_runtime.cpp"
click node_lua "https://github.com/gizclaw/gizos/blob/main/libs/lua/src/runtime/h2_lua.c"
click node_network_protocols "https://github.com/gizclaw/gizos/blob/main/libs/bleikcp/src/h2_bleikcp_client.c"
click node_audio_mixer "https://github.com/gizclaw/gizos/blob/main/libs/audio_mixer/src/h2_audio_mixer.c"
click node_desktop_support "https://github.com/gizclaw/gizos/blob/main/libs/pal/providers/desktop/app_support/h2_desktop_app_support.h"
click node_pal_providers "https://github.com/gizclaw/gizos/tree/main/libs/pal/providers"
click node_native_components "https://github.com/gizclaw/gizos/tree/main/native_component_src"
click node_boards "https://github.com/gizclaw/gizos/tree/main/boards"
click node_gizclaw "https://github.com/gizclaw/gizos/blob/main/libs/gizclaw/src/h2_gizclaw_client.c"
click node_ble_config "https://github.com/gizclaw/gizos/blob/main/libs/ble_wifi_config/src/h2_ble_wifi_config_service.c"
click node_loader_host "https://github.com/gizclaw/gizos/tree/main/libs/h2loader_host/src"

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_app_examples,node_h2loader,node_games,node_showcase toneBlue
class node_runtime,node_pal toneAmber
class node_game_runtime,node_lua,node_network_protocols,node_audio_mixer toneMint
class node_desktop_support,node_pal_providers,node_native_components,node_boards toneRose
class node_gizclaw,node_ble_config,node_loader_host,node_consumer toneIndigo
```

## Components

### Applications

- [Apps and examples](https://github.com/gizclaw/gizos/tree/main/projects): `projects`
- [H2Loader](https://github.com/gizclaw/gizos/blob/main/projects/h2loader/apps/loader/app/app.c): `projects/h2loader/apps/loader/app/app.c`
- [PIXA games](https://github.com/gizclaw/gizos/blob/main/projects/pixa_games/apps/dinodive/app/app.c): `projects/pixa_games/apps/dinodive/app/app.c`
- [Showcase app](https://github.com/gizclaw/gizos/blob/main/projects/showcase/targets/cc_binary/showcase/main.cpp): `projects/showcase/targets/cc_binary/showcase/main.cpp`

### Runtime and PAL

- [Application runtime](https://github.com/gizclaw/gizos/tree/main/libs/runtime): `libs/runtime`
- [PAL contracts](https://github.com/gizclaw/gizos/tree/main/libs/pal/include/h2/pal): `libs/pal/include/h2/pal`

### Reusable Libraries

- [Game runtime](https://github.com/gizclaw/gizos/blob/main/libs/game_runtime/src/h2_game_runtime.cpp): `libs/game_runtime/src/h2_game_runtime.cpp`
- [Lua runtime](https://github.com/gizclaw/gizos/blob/main/libs/lua/src/runtime/h2_lua.c): `libs/lua/src/runtime/h2_lua.c`
- [Networking and protocols](https://github.com/gizclaw/gizos/blob/main/libs/bleikcp/src/h2_bleikcp_client.c): `libs/bleikcp/src/h2_bleikcp_client.c`
- [Audio mixer](https://github.com/gizclaw/gizos/blob/main/libs/audio_mixer/src/h2_audio_mixer.c): `libs/audio_mixer/src/h2_audio_mixer.c`

### Platform Integrations

- [Desktop support](https://github.com/gizclaw/gizos/blob/main/libs/pal/providers/desktop/app_support/h2_desktop_app_support.h): `libs/pal/providers/desktop/app_support/h2_desktop_app_support.h`
- [PAL providers](https://github.com/gizclaw/gizos/tree/main/libs/pal/providers): `libs/pal/providers`
- [Native components](https://github.com/gizclaw/gizos/tree/main/native_component_src): `native_component_src`
- [Boards and SDKs](https://github.com/gizclaw/gizos/tree/main/boards): `boards`

### Device Services

- [GizClaw client](https://github.com/gizclaw/gizos/blob/main/libs/gizclaw/src/h2_gizclaw_client.c): `libs/gizclaw/src/h2_gizclaw_client.c`
- [BLE Wi-Fi setup](https://github.com/gizclaw/gizos/blob/main/libs/ble_wifi_config/src/h2_ble_wifi_config_service.c): `libs/ble_wifi_config/src/h2_ble_wifi_config_service.c`
- [Loader host services](https://github.com/gizclaw/gizos/tree/main/libs/h2loader_host/src): `libs/h2loader_host/src`

### Other components

- **Product developer**

## Connections

- Product developer → Apps and examples: composes (evidence: `README.md`)
- Apps and examples → Application runtime: uses runtime (evidence: `README.md`)
- H2Loader → Application runtime: uses runtime (evidence: `README.md`)
- PIXA games → Game runtime: uses game APIs (evidence: `projects/pixa_games/apps/dinodive/app/app.c`)
- PIXA games → Application runtime: uses runtime (evidence: `projects/pixa_games/apps/dinodive/app/app.c`)
- Showcase app → Application runtime: configures runtime (evidence: `projects/showcase/targets/cc_binary/showcase/main.cpp`)
- Application runtime → PAL contracts: uses contracts (evidence: `README.md`)
- Game runtime → PAL contracts: uses audio and display
- Lua runtime → PAL contracts: uses PAL services
- BLE Wi-Fi setup → Application runtime: uses runtime (evidence: `libs/ble_wifi_config/src/h2_ble_wifi_config_service.c`)
- Desktop support → Application runtime: provides runtime config (evidence: `libs/pal/providers/desktop/app_support/h2_desktop_app_support.h`)
- Showcase app → Desktop support: uses desktop support (evidence: `projects/showcase/targets/cc_binary/showcase/main.cpp`)
- PAL contracts → PAL providers: implemented by (evidence: `README.md`)
- PAL providers → Native components: integrates (evidence: `README.md`)
- Native components → Boards and SDKs: targets boards (evidence: `README.md`)
- H2Loader → Loader host services: uses loader services
- GizClaw client → PAL contracts: uses PAL contracts
- Networking and protocols → PAL contracts: uses PAL networking
- Audio mixer → PAL contracts: uses audio