# andrisgauracs/bevel-os architecture

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

- Interactive diagram: https://gitdiagram.com/andrisgauracs/bevel-os
- Repository: https://github.com/andrisgauracs/bevel-os

## Overview

Bevel OS is an ESP32-S3 graphical desktop. Its runtime starts the display, storage, window manager, loadable-app support, and networking, then enters the desktop event loop. Users work through built-in programs or launch separate ELF apps from the drive; files, network browsing, and windowed interaction are distinct product stages. The graph preserves the documented desktop, input, display, storage, networking, and app capabilities. Some subsystem paths are supported by the tree and README rather than inspected implementation; those links are omitted where call ownership is not established.

Main entry points: [`main/apps.c`](https://github.com/andrisgauracs/bevel-os/blob/main/main/apps.c) (Built-in app registry), [`main/main.c`](https://github.com/andrisgauracs/bevel-os/blob/main/main/main.c) (Boot and GUI task), [`main/fsutil.h`](https://github.com/andrisgauracs/bevel-os/blob/main/main/fsutil.h) (Filesystem helpers), [`main/storage.c`](https://github.com/andrisgauracs/bevel-os/blob/main/main/storage.c) (Flash FAT drive)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and UI"]
  node_boot["Boot and GUI task<br/>[main.c]"]
  node_window["Window manager<br/>[wm.c]"]
  node_widgets["Widget toolkit<br/>[ui.c]"]
  node_compositor["Damage compositor<br/>[comp.c]"]
  node_graphics["Graphics primitives<br/>[gfx.c]"]
end

subgraph group_apps["Applications"]
  node_builtins["Built-in app registry<br/>[apps.c]"]
  node_files["File manager<br/>[app_files.c]"]
  node_editor["Text editor<br/>[app_editor.c]"]
  node_viewer["Picture viewer<br/>[app_misc.c]"]
  node_systemapps["System utilities<br/>[app_misc.c]"]
  node_terminal["Terminal<br/>[shell.c]"]
  node_browser["Text web browser<br/>[app_browser.c]"]
  node_networkui["Network settings<br/>[app_net.c]"]
  node_loader["ELF app loader<br/>[app_loader.c]"]
  node_doom["Doom app<br/>[doom_bevel.c]"]
  node_snake["Snake app<br/>[Snake.c]"]
  node_api["App API<br/>[bevel.h]"]
end

subgraph group_platform["Device platform"]
  node_input["Input routing<br/>[input.c]"]
  node_usb["USB host input<br/>[usb_input.c]"]
  node_vga["VGA scan-out<br/>[vga.c]"]
end

subgraph group_data["Storage and network"]
  node_fshelpers["Filesystem helpers<br/>[fsutil.h]"]
  node_storage[("Flash FAT drive<br/>[storage.c]")]
  node_net["Wi-Fi networking<br/>[net.c]"]
end

subgraph group_external["External systems"]
  node_wifi(("Wi-Fi service"))
  node_drive[("On-device drive")]
end

node_user(("Desktop user"))

node_user -->|"operates"| node_window
node_boot -->|"initializes"| node_vga
node_boot -->|"initializes"| node_input
node_boot -->|"mounts"| node_storage
node_boot -->|"starts"| node_window
node_boot -->|"starts"| node_loader
node_boot -->|"starts"| node_net
node_input -.->|"receives input"| node_usb
node_window -->|"invalidates regions"| node_compositor
node_compositor -->|"paints strips"| node_graphics
node_compositor -.->|"flushes framebuffer"| node_vga
node_builtins -->|"launches"| node_files
node_builtins -->|"launches"| node_editor
node_builtins -->|"launches"| node_browser
node_builtins -->|"launches"| node_networkui
node_builtins -->|"launches"| node_terminal
node_builtins -->|"launches"| node_systemapps
node_builtins -->|"launches"| node_viewer
node_files -->|"uses file helpers"| node_fshelpers
node_editor -->|"uses file helpers"| node_fshelpers
node_terminal -->|"uses file helpers"| node_fshelpers
node_browser -->|"uses networking"| node_net
node_networkui -.->|"configures network"| node_net
node_fshelpers -.->|"accesses drive"| node_storage
node_storage -->|"mounts"| node_drive
node_net -.->|"uses"| node_wifi
node_loader -.->|"loads drive apps"| node_storage
node_loader -->|"provides interface"| node_api
node_doom -->|"calls app API"| node_api
node_snake -->|"uses app API"| node_api

click node_boot "https://github.com/andrisgauracs/bevel-os/blob/main/main/main.c"
click node_window "https://github.com/andrisgauracs/bevel-os/blob/main/main/wm.c"
click node_widgets "https://github.com/andrisgauracs/bevel-os/blob/main/main/ui.c"
click node_compositor "https://github.com/andrisgauracs/bevel-os/blob/main/main/comp.c"
click node_graphics "https://github.com/andrisgauracs/bevel-os/blob/main/main/gfx.c"
click node_input "https://github.com/andrisgauracs/bevel-os/blob/main/main/input.c"
click node_usb "https://github.com/andrisgauracs/bevel-os/blob/main/main/usb_input.c"
click node_vga "https://github.com/andrisgauracs/bevel-os/blob/main/main/vga.c"
click node_builtins "https://github.com/andrisgauracs/bevel-os/blob/main/main/apps.c"
click node_files "https://github.com/andrisgauracs/bevel-os/blob/main/main/app_files.c"
click node_editor "https://github.com/andrisgauracs/bevel-os/blob/main/main/app_editor.c"
click node_viewer "https://github.com/andrisgauracs/bevel-os/blob/main/main/app_misc.c"
click node_systemapps "https://github.com/andrisgauracs/bevel-os/blob/main/main/app_misc.c"
click node_terminal "https://github.com/andrisgauracs/bevel-os/blob/main/main/shell.c"
click node_browser "https://github.com/andrisgauracs/bevel-os/blob/main/main/app_browser.c"
click node_networkui "https://github.com/andrisgauracs/bevel-os/blob/main/main/app_net.c"
click node_loader "https://github.com/andrisgauracs/bevel-os/blob/main/main/app_loader.c"
click node_doom "https://github.com/andrisgauracs/bevel-os/blob/main/apps/doom/doom_bevel.c"
click node_snake "https://github.com/andrisgauracs/bevel-os/blob/main/apps/Snake.c"
click node_api "https://github.com/andrisgauracs/bevel-os/blob/main/apps/bevel.h"
click node_fshelpers "https://github.com/andrisgauracs/bevel-os/blob/main/main/fsutil.h"
click node_storage "https://github.com/andrisgauracs/bevel-os/blob/main/main/storage.c"
click node_net "https://github.com/andrisgauracs/bevel-os/blob/main/main/net.c"

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_boot,node_window,node_widgets,node_compositor,node_graphics,node_user toneBlue
class node_builtins,node_files,node_editor,node_viewer,node_systemapps,node_terminal,node_browser,node_networkui,node_loader,node_doom,node_snake,node_api toneAmber
class node_input,node_usb,node_vga toneMint
class node_fshelpers,node_storage,node_net toneRose
class node_wifi,node_drive toneIndigo
```

## Components

### Desktop and UI

- [Boot and GUI task](https://github.com/andrisgauracs/bevel-os/blob/main/main/main.c): `main/main.c`
- [Window manager](https://github.com/andrisgauracs/bevel-os/blob/main/main/wm.c): `main/wm.c`
- [Widget toolkit](https://github.com/andrisgauracs/bevel-os/blob/main/main/ui.c): `main/ui.c`
- [Damage compositor](https://github.com/andrisgauracs/bevel-os/blob/main/main/comp.c): `main/comp.c`
- [Graphics primitives](https://github.com/andrisgauracs/bevel-os/blob/main/main/gfx.c): `main/gfx.c`

### Applications

- [Built-in app registry](https://github.com/andrisgauracs/bevel-os/blob/main/main/apps.c): `main/apps.c`
- [File manager](https://github.com/andrisgauracs/bevel-os/blob/main/main/app_files.c): `main/app_files.c`
- [Text editor](https://github.com/andrisgauracs/bevel-os/blob/main/main/app_editor.c): `main/app_editor.c`
- [Picture viewer](https://github.com/andrisgauracs/bevel-os/blob/main/main/app_misc.c): `main/app_misc.c`
- [System utilities](https://github.com/andrisgauracs/bevel-os/blob/main/main/app_misc.c): `main/app_misc.c`
- [Terminal](https://github.com/andrisgauracs/bevel-os/blob/main/main/shell.c): `main/shell.c`
- [Text web browser](https://github.com/andrisgauracs/bevel-os/blob/main/main/app_browser.c): `main/app_browser.c`
- [Network settings](https://github.com/andrisgauracs/bevel-os/blob/main/main/app_net.c): `main/app_net.c`
- [ELF app loader](https://github.com/andrisgauracs/bevel-os/blob/main/main/app_loader.c): `main/app_loader.c`
- [Doom app](https://github.com/andrisgauracs/bevel-os/blob/main/apps/doom/doom_bevel.c): `apps/doom/doom_bevel.c`
- [Snake app](https://github.com/andrisgauracs/bevel-os/blob/main/apps/Snake.c): `apps/Snake.c`
- [App API](https://github.com/andrisgauracs/bevel-os/blob/main/apps/bevel.h): `apps/bevel.h`

### Device platform

- [Input routing](https://github.com/andrisgauracs/bevel-os/blob/main/main/input.c): `main/input.c`
- [USB host input](https://github.com/andrisgauracs/bevel-os/blob/main/main/usb_input.c): `main/usb_input.c`
- [VGA scan-out](https://github.com/andrisgauracs/bevel-os/blob/main/main/vga.c): `main/vga.c`

### Storage and network

- [Filesystem helpers](https://github.com/andrisgauracs/bevel-os/blob/main/main/fsutil.h): `main/fsutil.h`
- [Flash FAT drive](https://github.com/andrisgauracs/bevel-os/blob/main/main/storage.c): `main/storage.c`
- [Wi-Fi networking](https://github.com/andrisgauracs/bevel-os/blob/main/main/net.c): `main/net.c`

### External systems

- **Wi-Fi service**
- **On-device drive**

### Other components

- **Desktop user**

## Connections

- Desktop user → Window manager: operates
- Boot and GUI task → VGA scan-out: initializes (evidence: `main/main.c`)
- Boot and GUI task → Input routing: initializes (evidence: `main/main.c`)
- Boot and GUI task → Flash FAT drive: mounts (evidence: `main/main.c`)
- Boot and GUI task → Window manager: starts (evidence: `main/main.c`)
- Boot and GUI task → ELF app loader: starts (evidence: `main/main.c`)
- Boot and GUI task → Wi-Fi networking: starts (evidence: `main/main.c`)
- Input routing → USB host input: receives input
- Window manager → Damage compositor: invalidates regions (evidence: `main/wm.c`)
- Damage compositor → Graphics primitives: paints strips
- Damage compositor → VGA scan-out: flushes framebuffer
- Built-in app registry → File manager: launches (evidence: `main/apps.c`)
- Built-in app registry → Text editor: launches (evidence: `main/apps.c`)
- Built-in app registry → Text web browser: launches (evidence: `main/apps.c`)
- Built-in app registry → Network settings: launches (evidence: `main/apps.c`)
- Built-in app registry → Terminal: launches (evidence: `main/apps.c`)
- Built-in app registry → System utilities: launches (evidence: `main/apps.c`)
- Built-in app registry → Picture viewer: launches (evidence: `main/apps.c`)
- File manager → Filesystem helpers: uses file helpers (evidence: `main/app_files.c`)
- Text editor → Filesystem helpers: uses file helpers (evidence: `main/app_editor.c`)
- Terminal → Filesystem helpers: uses file helpers (evidence: `main/shell.c`)
- Text web browser → Wi-Fi networking: uses networking (evidence: `main/app_browser.c`)
- Network settings → Wi-Fi networking: configures network
- Filesystem helpers → Flash FAT drive: accesses drive
- Flash FAT drive → On-device drive: mounts (evidence: `main/storage.c`)
- Wi-Fi networking → Wi-Fi service: uses
- ELF app loader → Flash FAT drive: loads drive apps
- ELF app loader → App API: provides interface (evidence: `main/app_loader.c`)
- Doom app → App API: calls app API (evidence: `apps/doom/doom_bevel.c`)
- Snake app → App API: uses app API (evidence: `apps/Snake.c`)
