# nextos-ports/nextos-framework architecture

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

- Interactive diagram: https://gitdiagram.com/nextos-ports/nextos-framework
- Repository: https://github.com/nextos-ports/nextos-framework

## Overview

NextOS Framework is a collection for researching, adapting, and running Android game ports on Linux ARM handhelds—not a single game or installer. The documented workflow starts with engine and source research, then uses the preserved V5 framework components and per-title port code to build and run a game, with device testing still required. The README also identifies bilingual engine guides and a catalog of selected sources. Sampled port launchers show game-specific loader and compatibility work; broader framework links reflect README descriptions, not inspection of every subsystem.

Main entry points: [`ports/offtheroad-nextos/upstream/src/main.c`](https://github.com/nextos-ports/nextos-framework/blob/main/ports/offtheroad-nextos/upstream/src/main.c) (Port Launcher), [`framework`](https://github.com/nextos-ports/nextos-framework/tree/main/framework) (V5 Components), [`portando_unity`](https://github.com/nextos-ports/nextos-framework/tree/main/portando_unity) (Engine Guides), [`catalog/README.md`](https://github.com/nextos-ports/nextos-framework/blob/main/catalog/README.md) (Selected Sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Research and Catalog"]
  node_guides["Engine Guides"]
  node_catalog["Selected Sources<br/>[README.md]"]
end

subgraph group_runtime["Framework Runtime"]
  node_framework["V5 Components"]
  node_so_loader["ELF Loader<br/>[nxloader.c]"]
  node_compat["Android Compatibility<br/>[nxcompat.c]"]
  node_input["Input Routing<br/>[nxinput.c]"]
  node_graphics["Graphics Runtime<br/>[nxgl_present.c]"]
  node_audio["Audio Runtime<br/>[nxaudio.c]"]
  node_android["Android Shims<br/>[nxandroid.c]"]
  node_observability["Runtime Evidence<br/>[nxobs_crash.c]"]
end

subgraph group_ports["Game Ports"]
  node_portentry["Port Launcher<br/>[main.c]"]
  node_nxextract["NXExtract"]
end

subgraph group_device["Device Integration"]
  node_handheld(("Linux ARM Handheld"))
end

node_engineer(("Port Engineer"))
node_gamecode["Game Payload"]

node_engineer -->|"consults"| node_guides
node_engineer -->|"selects source"| node_catalog
node_guides -->|"guides adaptation"| node_portentry
node_catalog -->|"identifies sources"| node_gamecode
node_gamecode -->|"supplies payload"| node_portentry
node_portentry -->|"loads guest"| node_so_loader
node_portentry -->|"uses shims"| node_compat
node_portentry -->|"routes controls"| node_input
node_portentry -->|"presents frames"| node_graphics
node_portentry -->|"uses audio"| node_audio
node_portentry -->|"adapts Android APIs"| node_android
node_portentry -->|"records evidence"| node_observability
node_framework -->|"provides runtime"| node_so_loader
node_framework -->|"provides runtime"| node_compat
node_framework -->|"provides runtime"| node_input
node_framework -->|"provides runtime"| node_graphics
node_framework -->|"provides runtime"| node_audio
node_framework -->|"provides runtime"| node_android
node_framework -->|"provides runtime"| node_observability
node_nxextract -->|"installs port"| node_handheld
node_portentry -->|"runs on"| node_handheld

click node_guides "https://github.com/nextos-ports/nextos-framework/tree/main/portando_unity"
click node_catalog "https://github.com/nextos-ports/nextos-framework/blob/main/catalog/README.md"
click node_portentry "https://github.com/nextos-ports/nextos-framework/blob/main/ports/offtheroad-nextos/upstream/src/main.c"
click node_framework "https://github.com/nextos-ports/nextos-framework/tree/main/framework"
click node_so_loader "https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxloader/src/nxloader.c"
click node_compat "https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxcompat/src/nxcompat.c"
click node_input "https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxinput/src/nxinput.c"
click node_graphics "https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxgl/src/nxgl_present.c"
click node_audio "https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxaudio/src/nxaudio.c"
click node_android "https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxandroid/src/nxandroid.c"
click node_observability "https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxobs/src/nxobs_crash.c"
click node_nxextract "https://github.com/nextos-ports/nextos-framework/tree/main/suportando_outros_devices/extrator-universal"

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_guides,node_catalog toneBlue
class node_framework,node_so_loader,node_compat,node_input,node_graphics,node_audio,node_android,node_observability toneAmber
class node_portentry,node_nxextract toneMint
class node_handheld toneRose
class node_engineer,node_gamecode toneIndigo
```

## Components

### Research and Catalog

- [Engine Guides](https://github.com/nextos-ports/nextos-framework/tree/main/portando_unity): `portando_unity`
- [Selected Sources](https://github.com/nextos-ports/nextos-framework/blob/main/catalog/README.md): `catalog/README.md`

### Framework Runtime

- [V5 Components](https://github.com/nextos-ports/nextos-framework/tree/main/framework): `framework`
- [ELF Loader](https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxloader/src/nxloader.c): `framework/nxloader/src/nxloader.c`
- [Android Compatibility](https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxcompat/src/nxcompat.c): `framework/nxcompat/src/nxcompat.c`
- [Input Routing](https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxinput/src/nxinput.c): `framework/nxinput/src/nxinput.c`
- [Graphics Runtime](https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxgl/src/nxgl_present.c): `framework/nxgl/src/nxgl_present.c`
- [Audio Runtime](https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxaudio/src/nxaudio.c): `framework/nxaudio/src/nxaudio.c`
- [Android Shims](https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxandroid/src/nxandroid.c): `framework/nxandroid/src/nxandroid.c`
- [Runtime Evidence](https://github.com/nextos-ports/nextos-framework/blob/main/framework/nxobs/src/nxobs_crash.c): `framework/nxobs/src/nxobs_crash.c`

### Game Ports

- [Port Launcher](https://github.com/nextos-ports/nextos-framework/blob/main/ports/offtheroad-nextos/upstream/src/main.c): `ports/offtheroad-nextos/upstream/src/main.c`
- [NXExtract](https://github.com/nextos-ports/nextos-framework/tree/main/suportando_outros_devices/extrator-universal): `suportando_outros_devices/extrator-universal`

### Device Integration

- **Linux ARM Handheld**

### Other components

- **Port Engineer**
- **Game Payload**

## Connections

- Port Engineer → Engine Guides: consults
- Port Engineer → Selected Sources: selects source
- Engine Guides → Port Launcher: guides adaptation
- Selected Sources → Game Payload: identifies sources
- Game Payload → Port Launcher: supplies payload
- Port Launcher → ELF Loader: loads guest
- Port Launcher → Android Compatibility: uses shims
- Port Launcher → Input Routing: routes controls
- Port Launcher → Graphics Runtime: presents frames
- Port Launcher → Audio Runtime: uses audio
- Port Launcher → Android Shims: adapts Android APIs
- Port Launcher → Runtime Evidence: records evidence
- V5 Components → ELF Loader: provides runtime
- V5 Components → Android Compatibility: provides runtime
- V5 Components → Input Routing: provides runtime
- V5 Components → Graphics Runtime: provides runtime
- V5 Components → Audio Runtime: provides runtime
- V5 Components → Android Shims: provides runtime
- V5 Components → Runtime Evidence: provides runtime
- NXExtract → Linux ARM Handheld: installs port
- Port Launcher → Linux ARM Handheld: runs on