# ardyanptr/c3os architecture

> Architecture diagram of the GitHub repository ardyanptr/c3os, 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/ardyanptr/c3os
- Repository: https://github.com/ardyanptr/c3os

## Overview

C3OS is an embedded operating-system environment for ESP32-C3 and ESP8266 boards, combining a native command interface, on-device applications, persistent storage, and Lua scripting. Its principal documented workflow is user input through the firmware shell, command dispatch to a handler or script, and feedback through local display or serial. The tree also shows app/process management, games, Wi-Fi tools, crash recovery, and power management. Shell and storage relationships are documented in the README; sampled code confirms selected app, crash, and power behaviors, but not all subsystem wiring.

Main entry points: [`src/main.cpp`](https://github.com/ardyanptr/c3os/blob/main/src/main.cpp) (Command Shell), [`src/component/process_manager.cpp`](https://github.com/ardyanptr/c3os/blob/main/src/component/process_manager.cpp) (Process Manager), [`src/system16/lua_l/lua_l.cpp`](https://github.com/ardyanptr/c3os/blob/main/src/system16/lua_l/lua_l.cpp) (Lua Integration), [`src/system16/C3FS/C3FS.cpp`](https://github.com/ardyanptr/c3os/blob/main/src/system16/C3FS/C3FS.cpp) (C3FS Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Firmware Core"]
  node_shell["Command Shell<br/>[main.cpp]"]
  node_boot["BIOS and Boot<br/>[BIOS.cpp]"]
  node_app_catalog["App Catalog<br/>[app.h]"]
  node_process_manager["Process Manager"]
  node_display_io["Display and Serial<br/>[ui_.h]"]
  node_buttons["Button Input<br/>[button.cpp]"]
end

subgraph group_apps["Applications"]
  node_essential_apps["Essential Apps"]
  node_game_clients["Game Clients"]
  node_wifi_apps["Wi-Fi Tools"]
  node_app_store["App Store<br/>[StoreManager.cpp]"]
  node_file_manager["File Manager<br/>[FileManager.cpp]"]
end

subgraph group_runtime["Storage and Runtime"]
  node_lua_bridge["Lua Integration<br/>[lua_l.cpp]"]
  node_lua_runtime["Lua Runtime<br/>[lapi.c]"]
  node_filesystem["C3FS Storage<br/>[C3FS.cpp]"]
  node_fs_cache["Filesystem Cache<br/>[C3FS_Cache.cpp]"]
end

subgraph group_system["System Services"]
  node_crash_engine["Crash Engine<br/>[CrashEngine.cpp]"]
  node_power_manager["Power Manager<br/>[power_manager.cpp]"]
  node_task_manager_ui["Task Manager UI<br/>[task_manager.h]"]
  node_wifi_service["Wi-Fi Service<br/>[wifiservice.cpp]"]
end

node_user(("User"))
node_littlefs[("LittleFS")]

node_user -->|"enters commands"| node_shell
node_user -->|"presses controls"| node_buttons
node_shell -->|"outputs feedback"| node_display_io
node_shell -->|"invokes scripts"| node_lua_bridge
node_lua_bridge -->|"runs Lua"| node_lua_runtime
node_boot -->|"starts firmware"| node_shell
node_app_catalog -->|"provides app entries"| node_process_manager
node_process_manager -->|"clears app display"| node_display_io
node_process_manager -->|"manages processes"| node_task_manager_ui
node_shell -->|"starts game clients"| node_game_clients
node_shell -->|"dispatches app handlers"| node_essential_apps
node_file_manager -->|"scans files"| node_filesystem
node_file_manager -->|"runs Lua scripts"| node_lua_bridge
node_app_store -->|"uses Wi-Fi"| node_wifi_service
node_app_store -->|"writes downloads"| node_littlefs
node_filesystem -->|"stores files"| node_littlefs
node_fs_cache -->|"caches filesystem data"| node_filesystem
node_crash_engine -->|"persists crash logs"| node_littlefs
node_power_manager -->|"changes Wi-Fi power"| node_wifi_service
node_power_manager -->|"dims display"| node_display_io
node_wifi_apps -.->|"uses Wi-Fi"| node_wifi_service

click node_shell "https://github.com/ardyanptr/c3os/blob/main/src/main.cpp"
click node_boot "https://github.com/ardyanptr/c3os/blob/main/src/system16/BIOS.cpp"
click node_app_catalog "https://github.com/ardyanptr/c3os/blob/main/src/system16/app.h"
click node_process_manager "https://github.com/ardyanptr/c3os/blob/main/src/component/process_manager.cpp"
click node_display_io "https://github.com/ardyanptr/c3os/blob/main/src/component/ui_.h"
click node_buttons "https://github.com/ardyanptr/c3os/blob/main/src/component/button.cpp"
click node_essential_apps "https://github.com/ardyanptr/c3os/tree/main/src/app/Essential"
click node_game_clients "https://github.com/ardyanptr/c3os/tree/main/src/app/Game"
click node_wifi_apps "https://github.com/ardyanptr/c3os/tree/main/src/app/WiFiApp"
click node_app_store "https://github.com/ardyanptr/c3os/blob/main/src/app/Essential/StoreManager.cpp"
click node_file_manager "https://github.com/ardyanptr/c3os/blob/main/src/app/Essential/FileManager.cpp"
click node_lua_bridge "https://github.com/ardyanptr/c3os/blob/main/src/system16/lua_l/lua_l.cpp"
click node_lua_runtime "https://github.com/ardyanptr/c3os/blob/main/lib/lua/src/lapi.c"
click node_filesystem "https://github.com/ardyanptr/c3os/blob/main/src/system16/C3FS/C3FS.cpp"
click node_fs_cache "https://github.com/ardyanptr/c3os/blob/main/src/system16/C3FS/C3FS_Cache.cpp"
click node_crash_engine "https://github.com/ardyanptr/c3os/blob/main/src/app/CrashApp/CrashEngine.cpp"
click node_power_manager "https://github.com/ardyanptr/c3os/blob/main/src/system16/power_manager.cpp"
click node_task_manager_ui "https://github.com/ardyanptr/c3os/blob/main/src/UI/task_manager.h"
click node_wifi_service "https://github.com/ardyanptr/c3os/blob/main/src/component/wifiservice.cpp"

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_shell,node_boot,node_app_catalog,node_process_manager,node_display_io,node_buttons,node_user toneBlue
class node_essential_apps,node_game_clients,node_wifi_apps,node_app_store,node_file_manager,node_littlefs toneAmber
class node_lua_bridge,node_lua_runtime,node_filesystem,node_fs_cache toneMint
class node_crash_engine,node_power_manager,node_task_manager_ui,node_wifi_service toneRose
```

## Components

### Firmware Core

- [Command Shell](https://github.com/ardyanptr/c3os/blob/main/src/main.cpp): `src/main.cpp`
- [BIOS and Boot](https://github.com/ardyanptr/c3os/blob/main/src/system16/BIOS.cpp): `src/system16/BIOS.cpp`
- [App Catalog](https://github.com/ardyanptr/c3os/blob/main/src/system16/app.h): `src/system16/app.h`
- [Process Manager](https://github.com/ardyanptr/c3os/blob/main/src/component/process_manager.cpp): `src/component/process_manager.cpp`
- [Display and Serial](https://github.com/ardyanptr/c3os/blob/main/src/component/ui_.h): `src/component/ui_.h`
- [Button Input](https://github.com/ardyanptr/c3os/blob/main/src/component/button.cpp): `src/component/button.cpp`

### Applications

- [Essential Apps](https://github.com/ardyanptr/c3os/tree/main/src/app/Essential): `src/app/Essential`
- [Game Clients](https://github.com/ardyanptr/c3os/tree/main/src/app/Game): `src/app/Game`
- [Wi-Fi Tools](https://github.com/ardyanptr/c3os/tree/main/src/app/WiFiApp): `src/app/WiFiApp`
- [App Store](https://github.com/ardyanptr/c3os/blob/main/src/app/Essential/StoreManager.cpp): `src/app/Essential/StoreManager.cpp`
- [File Manager](https://github.com/ardyanptr/c3os/blob/main/src/app/Essential/FileManager.cpp): `src/app/Essential/FileManager.cpp`

### Storage and Runtime

- [Lua Integration](https://github.com/ardyanptr/c3os/blob/main/src/system16/lua_l/lua_l.cpp): `src/system16/lua_l/lua_l.cpp`
- [Lua Runtime](https://github.com/ardyanptr/c3os/blob/main/lib/lua/src/lapi.c): `lib/lua/src/lapi.c`
- [C3FS Storage](https://github.com/ardyanptr/c3os/blob/main/src/system16/C3FS/C3FS.cpp): `src/system16/C3FS/C3FS.cpp`
- [Filesystem Cache](https://github.com/ardyanptr/c3os/blob/main/src/system16/C3FS/C3FS_Cache.cpp): `src/system16/C3FS/C3FS_Cache.cpp`

### System Services

- [Crash Engine](https://github.com/ardyanptr/c3os/blob/main/src/app/CrashApp/CrashEngine.cpp): `src/app/CrashApp/CrashEngine.cpp`
- [Power Manager](https://github.com/ardyanptr/c3os/blob/main/src/system16/power_manager.cpp): `src/system16/power_manager.cpp`
- [Task Manager UI](https://github.com/ardyanptr/c3os/blob/main/src/UI/task_manager.h): `src/UI/task_manager.h`
- [Wi-Fi Service](https://github.com/ardyanptr/c3os/blob/main/src/component/wifiservice.cpp): `src/component/wifiservice.cpp`

### Other components

- **User**
- **LittleFS**

## Connections

- User → Command Shell: enters commands
- User → Button Input: presses controls
- Command Shell → Display and Serial: outputs feedback
- Command Shell → Lua Integration: invokes scripts
- Lua Integration → Lua Runtime: runs Lua
- BIOS and Boot → Command Shell: starts firmware
- App Catalog → Process Manager: provides app entries
- Process Manager → Display and Serial: clears app display
- Process Manager → Task Manager UI: manages processes
- Command Shell → Game Clients: starts game clients
- Command Shell → Essential Apps: dispatches app handlers
- File Manager → C3FS Storage: scans files
- File Manager → Lua Integration: runs Lua scripts
- App Store → Wi-Fi Service: uses Wi-Fi
- App Store → LittleFS: writes downloads
- C3FS Storage → LittleFS: stores files
- Filesystem Cache → C3FS Storage: caches filesystem data
- Crash Engine → LittleFS: persists crash logs
- Power Manager → Wi-Fi Service: changes Wi-Fi power
- Power Manager → Display and Serial: dims display
- Wi-Fi Tools → Wi-Fi Service: uses Wi-Fi