# 0nera/synapseos-userspace architecture

> Architecture diagram of the GitHub repository 0nera/synapseos-userspace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0nera/synapseos-userspace
- Repository: https://github.com/0nera/synapseos-userspace

## Overview

#### Purpose and Build Surface
This repository supplies SynapseOS user-space programs plus a small C runtime/library for x86_64 OS processes. Applications are built through `apps/Makefile`; their shared linker layout is defined in `apps/apps.ld`. The expected output is standalone executables copied into a SynapseOS disk image.

#### Process Startup and ABI Boundary
User programs enter through custom assembly startup code in `synlibc/crt0.asm`, which establishes the C runtime before application `main`. Low-level kernel interaction crosses an assembly syscall boundary in `synlibc/syscall.asm`, exposed to C consumers through `synlibc/include/syscalls.h` and higher-level wrappers in `synlibc/synapi.c`.

#### Shared Userspace Runtime
`synlibc` is the common static runtime linked into applications. It provides foundational memory/string and POSIX-like facilities in `synlibc/mem.c`, `synlibc/string.c`, and `synlibc/posix.c`; public APIs are consolidated under `synlibc/include/synlibc.h`. This layer isolates applications from raw kernel ABI details.

#### Device and Graphics Interfaces
Hardware-facing APIs are represented as library interfaces rather than per-app drivers. HID input contracts reside in `synlibc/include/dev/hid.h`; virtual GPU access is defined by `synlibc/include/vgpu.h` and implemented in `synlibc/vgpu.c`. Applications using input or graphics should depend on these abstractions and their underlying syscall/API layer.

#### Application Suite
Each program is an independent userspace executable with its own `main`:
- System bootstrap/init: `apps/init/main.c`
- Interactive command environment: `apps/shell/main.c`
- Minimal validation/demo programs: `apps/hello/main.c`, `apps/tests/main.c`
- System-information display: `apps/synfetch/main.c`
- Additional interactive/game-style applications: `apps/doom/main.c`, `apps/tel/main.c`

`init` is the likely process-control entry application after the OS loads userspace; the shell and other binaries are peer executables deployed under `/apps`.

#### Configuration and Deployment Flow
`settings.ini` is a filesystem-root configuration artifact, parsed through `synlibc/ini.c` and its API in `synlibc/include/ini.h`. Build output is generated under `apps/apps-bin` (via `apps/Makefile`) and copied into a preexisting `x86_64.hdd` disk image with `mtools`; settings are copied separately to the image root. Runtime therefore depends on the SynapseOS kernel/image providing the expected filesystem, executable loader, syscall ABI, HID, and VGPU services.

#### Tooling and Execution Environment
The development path uses GNU Make, GCC, NASM, and mtools; QEMU is the intended x86_64 emulator/runtime. `run.sh` is the repository-level execution launcher, while CI is defined in `.github/workflows/ci.yml`.

Main entry points: [`synlibc/include/synlibc.h`](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/include/synlibc.h) (synlibc core), [`apps/Makefile`](https://github.com/0nera/synapseos-userspace/blob/master/apps/Makefile) (Application build), [`synlibc/synapi.c`](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/synapi.c) (Kernel API wrappers), [`apps/doom/main.c`](https://github.com/0nera/synapseos-userspace/blob/master/apps/doom/main.c) (Doom and tel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Shared Runtime"]
  node_crt0{{"Process startup<br/>assembly runtime<br/>[crt0.asm]"}}
  node_syscall{{"Syscall ABI<br/>assembly boundary<br/>[syscall.asm]"}}
  node_syscall_api["Syscall declarations<br/>C header<br/>[syscalls.h]"]
  node_synapi["Kernel API wrappers<br/>C runtime layer<br/>[synapi.c]"]
  node_synlibc["synlibc core<br/>static runtime<br/>[synlibc.h]"]
  node_ini["INI support<br/>runtime module<br/>[ini.c]"]
  node_device_apis["HID and VGPU APIs<br/>device interfaces<br/>[vgpu.c]"]
end

subgraph group_apps["Application Suite"]
  node_init["init<br/>bootstrap app<br/>[main.c]"]
  node_shell["shell<br/>interactive app<br/>[main.c]"]
  node_utility_apps["Utilities and demos<br/>application set<br/>[main.c]"]
  node_interactive_apps["Doom and tel<br/>interactive application set<br/>[main.c]"]
end

subgraph group_build["Build &amp; Deployment"]
  node_apps_make["Application build<br/>Makefile"]
  node_linker_layout["Shared linker layout<br/>linker script<br/>[apps.ld]"]
  node_app_binaries["Standalone executables<br/>build output"]
  node_disk_image[("SynapseOS disk image<br/>deployment image")]
  node_settings["Root settings<br/>configuration<br/>[settings.ini]"]
  node_ci["CI<br/>workflow<br/>[ci.yml]"]
end

subgraph group_platform["SynapseOS Platform"]
  node_synapseos{{"Kernel services<br/>OS platform"}}
  node_runner["QEMU launcher<br/>execution script<br/>[run.sh]"]
end

node_apps_make -->|"uses"| node_linker_layout
node_apps_make -->|"builds"| node_app_binaries
node_apps_make -->|"links"| node_synlibc
node_app_binaries -->|"copied with mtools"| node_disk_image
node_settings -->|"copied to root"| node_disk_image
node_crt0 -->|"starts"| node_synlibc
node_synlibc -->|"uses"| node_synapi
node_synapi -->|"declared by"| node_syscall_api
node_syscall_api -->|"crosses"| node_syscall
node_ini -->|"parses"| node_settings
node_device_apis -->|"uses kernel API"| node_synapi
node_init -->|"links"| node_synlibc
node_shell -->|"links"| node_synlibc
node_utility_apps -->|"links"| node_synlibc
node_interactive_apps -->|"uses input and graphics"| node_device_apis
node_interactive_apps -->|"links"| node_synlibc
node_syscall -->|"invokes"| node_synapseos
node_disk_image -->|"boots with"| node_synapseos
node_runner -->|"runs"| node_disk_image
node_ci -->|"builds"| node_apps_make

click node_apps_make "https://github.com/0nera/synapseos-userspace/blob/master/apps/Makefile"
click node_linker_layout "https://github.com/0nera/synapseos-userspace/blob/master/apps/apps.ld"
click node_settings "https://github.com/0nera/synapseos-userspace/blob/master/settings.ini"
click node_crt0 "https://github.com/0nera/synapseos-userspace/blob/master/synlibc/crt0.asm"
click node_syscall "https://github.com/0nera/synapseos-userspace/blob/master/synlibc/syscall.asm"
click node_syscall_api "https://github.com/0nera/synapseos-userspace/blob/master/synlibc/include/syscalls.h"
click node_synapi "https://github.com/0nera/synapseos-userspace/blob/master/synlibc/synapi.c"
click node_synlibc "https://github.com/0nera/synapseos-userspace/blob/master/synlibc/include/synlibc.h"
click node_ini "https://github.com/0nera/synapseos-userspace/blob/master/synlibc/ini.c"
click node_device_apis "https://github.com/0nera/synapseos-userspace/blob/master/synlibc/vgpu.c"
click node_init "https://github.com/0nera/synapseos-userspace/blob/master/apps/init/main.c"
click node_shell "https://github.com/0nera/synapseos-userspace/blob/master/apps/shell/main.c"
click node_utility_apps "https://github.com/0nera/synapseos-userspace/blob/master/apps/synfetch/main.c"
click node_interactive_apps "https://github.com/0nera/synapseos-userspace/blob/master/apps/doom/main.c"
click node_runner "https://github.com/0nera/synapseos-userspace/blob/master/run.sh"
click node_ci "https://github.com/0nera/synapseos-userspace/blob/master/.github/workflows/ci.yml"

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_crt0,node_syscall,node_syscall_api,node_synapi,node_synlibc,node_ini,node_device_apis toneBlue
class node_init,node_shell,node_utility_apps,node_interactive_apps toneAmber
class node_apps_make,node_linker_layout,node_app_binaries,node_disk_image,node_settings,node_ci toneMint
class node_synapseos,node_runner toneRose
```

## Components

### Shared Runtime

Static userspace library and process ABI boundary.

- [Process startup](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/crt0.asm): assembly runtime · Establishes C runtime before main. · `synlibc/crt0.asm`
- [Syscall ABI](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/syscall.asm): assembly boundary · `synlibc/syscall.asm`
- [Syscall declarations](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/include/syscalls.h): C header · `synlibc/include/syscalls.h`
- [Kernel API wrappers](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/synapi.c): C runtime layer · `synlibc/synapi.c`
- [synlibc core](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/include/synlibc.h): static runtime · Memory, strings, and POSIX-like facilities. · `synlibc/include/synlibc.h`
- [INI support](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/ini.c): runtime module · `synlibc/ini.c`
- [HID and VGPU APIs](https://github.com/0nera/synapseos-userspace/blob/master/synlibc/vgpu.c): device interfaces · Input contract and virtual GPU implementation. · `synlibc/vgpu.c`

### Application Suite

Independent executables deployed under /apps.

- [init](https://github.com/0nera/synapseos-userspace/blob/master/apps/init/main.c): bootstrap app · Likely first userspace process. · `apps/init/main.c`
- [shell](https://github.com/0nera/synapseos-userspace/blob/master/apps/shell/main.c): interactive app · `apps/shell/main.c`
- [Utilities and demos](https://github.com/0nera/synapseos-userspace/blob/master/apps/synfetch/main.c): application set · hello, tests, and synfetch executables. · `apps/synfetch/main.c`
- [Doom and tel](https://github.com/0nera/synapseos-userspace/blob/master/apps/doom/main.c): interactive application set · `apps/doom/main.c`

### Build & Deployment

Builds programs and installs them into the OS image.

- [Application build](https://github.com/0nera/synapseos-userspace/blob/master/apps/Makefile): Makefile · `apps/Makefile`
- [Shared linker layout](https://github.com/0nera/synapseos-userspace/blob/master/apps/apps.ld): linker script · `apps/apps.ld`
- **Standalone executables**: build output · Generated under apps/apps-bin.
- **SynapseOS disk image**: deployment image · Executables and root settings are copied here with mtools.
- [Root settings](https://github.com/0nera/synapseos-userspace/blob/master/settings.ini): configuration · `settings.ini`
- [CI](https://github.com/0nera/synapseos-userspace/blob/master/.github/workflows/ci.yml): workflow · `.github/workflows/ci.yml`

### SynapseOS Platform

Services supplied by the loaded OS image.

- **Kernel services**: OS platform · Provides loader, filesystem, syscall ABI, HID, and VGPU.
- [QEMU launcher](https://github.com/0nera/synapseos-userspace/blob/master/run.sh): execution script · `run.sh`

## Connections

- Application build → Shared linker layout: uses
- Application build → Standalone executables: builds
- Application build → synlibc core: links
- Standalone executables → SynapseOS disk image: copied with mtools
- Root settings → SynapseOS disk image: copied to root
- Process startup → synlibc core: starts
- synlibc core → Kernel API wrappers: uses
- Kernel API wrappers → Syscall declarations: declared by
- Syscall declarations → Syscall ABI: crosses
- INI support → Root settings: parses
- HID and VGPU APIs → Kernel API wrappers: uses kernel API
- init → synlibc core: links
- shell → synlibc core: links
- Utilities and demos → synlibc core: links
- Doom and tel → HID and VGPU APIs: uses input and graphics
- Doom and tel → synlibc core: links
- Syscall ABI → Kernel services: invokes
- SynapseOS disk image → Kernel services: boots with
- QEMU launcher → SynapseOS disk image: runs
- CI → Application build: builds