# referefref/maytera-os architecture

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

- Interactive diagram: https://gitdiagram.com/referefref/maytera-os
- Repository: https://github.com/referefref/maytera-os

## Overview

MayteraOS is an experimental x86-64 operating system whose principal user flow runs from desktop interaction through the built-in assistant’s typed tools, risk checks, consent, and kernel-enforced capabilities to an action and audit record. The desktop is backed by kernel services, filesystems, networking, and native applications; other documented capabilities include compatibility runtimes, games, and media. The graph preserves those product branches, but many links are documented rather than source-verified because their implementation files were not sampled.

Main entry points: [`userland/libc/aiclient.c`](https://github.com/referefref/maytera-os/blob/main/userland/libc/aiclient.c) (AI tool client), [`kernel/main.c`](https://github.com/referefref/maytera-os/blob/main/kernel/main.c) (Kernel core), [`userland/apps/aichat/main.c`](https://github.com/referefref/maytera-os/blob/main/userland/apps/aichat/main.c) (Maytera AI), [`kernel/gui/desktop.h`](https://github.com/referefref/maytera-os/blob/main/kernel/gui/desktop.h) (Consent prompt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ai["Assistant and Safety"]
  node_assistant["Maytera AI<br/>[main.c]"]
  node_toolclient["AI tool client<br/>[aiclient.c]"]
  node_contracts["App tool contracts<br/>[contract.h]"]
  node_consent["Consent prompt<br/>[desktop.h]"]
  node_capabilities["Capability enforcement<br/>[security.c]"]
  node_audit["Action audit<br/>[security.c]"]
end

subgraph group_desktop["Desktop Experience"]
  node_compositor["Desktop compositor<br/>[main.c]"]
  node_window["Window system<br/>[window.h]"]
  node_settings["Settings"]
  node_files["Files browser<br/>[main.c]"]
end

subgraph group_kernel["Kernel and Runtime"]
  node_kernel["Kernel core<br/>[main.c]"]
  node_process["Process and scheduler<br/>[process.c]"]
  node_memory["Virtual memory<br/>[vmm.c]"]
  node_services["Service lifecycle<br/>[services.c]"]
  node_boot["UEFI bootloader<br/>[bootloader.c]"]
end

subgraph group_io["Storage and Networking"]
  node_vfs["Virtual filesystem<br/>[vfs.c]"]
  node_filesystems["ext2 and FAT"]
  node_network["Network and TLS"]
end

subgraph group_apps["Applications and Compatibility"]
  node_apps["Native applications"]
  node_browser["Web browser<br/>[main.c]"]
  node_compat["DOS and Win16"]
  node_media["Media playback"]
  node_games["Games<br/>[main.c]"]
end

node_user(("Desktop user"))

node_user -->|"invokes"| node_assistant
node_assistant -->|"uses"| node_toolclient
node_toolclient -->|"exposes controls"| node_contracts
node_toolclient -->|"requests approval"| node_consent
node_consent -->|"grants scope"| node_capabilities
node_toolclient -->|"records outcome"| node_audit
node_capabilities -->|"gates syscalls"| node_kernel
node_user -->|"interacts with"| node_compositor
node_compositor -->|"manages windows"| node_window
node_user -->|"browses files"| node_files
node_kernel -->|"schedules"| node_process
node_kernel -->|"provides paging"| node_memory
node_services -->|"starts services"| node_process
node_vfs -->|"mounts"| node_filesystems
node_network -->|"fetches pages"| node_browser
node_user -->|"launches"| node_apps
node_user -->|"runs supplied software"| node_compat
node_user -->|"plays media"| node_media
node_user -->|"plays games"| node_games
node_boot -->|"boots"| node_kernel

click node_assistant "https://github.com/referefref/maytera-os/blob/main/userland/apps/aichat/main.c"
click node_toolclient "https://github.com/referefref/maytera-os/blob/main/userland/libc/aiclient.c"
click node_contracts "https://github.com/referefref/maytera-os/blob/main/userland/libc/contract.h"
click node_consent "https://github.com/referefref/maytera-os/blob/main/kernel/gui/desktop.h"
click node_capabilities "https://github.com/referefref/maytera-os/blob/main/kernel/security/security.c"
click node_audit "https://github.com/referefref/maytera-os/blob/main/kernel/security/security.c"
click node_compositor "https://github.com/referefref/maytera-os/blob/main/userland/apps/compositor/main.c"
click node_window "https://github.com/referefref/maytera-os/blob/main/kernel/gui/window.h"
click node_settings "https://github.com/referefref/maytera-os/tree/main/userland/apps"
click node_files "https://github.com/referefref/maytera-os/blob/main/userland/apps/files/main.c"
click node_kernel "https://github.com/referefref/maytera-os/blob/main/kernel/main.c"
click node_process "https://github.com/referefref/maytera-os/blob/main/kernel/proc/process.c"
click node_memory "https://github.com/referefref/maytera-os/blob/main/kernel/mm/vmm.c"
click node_services "https://github.com/referefref/maytera-os/blob/main/kernel/proc/services.c"
click node_vfs "https://github.com/referefref/maytera-os/blob/main/kernel/fs/vfs.c"
click node_filesystems "https://github.com/referefref/maytera-os/tree/main/kernel/fs"
click node_network "https://github.com/referefref/maytera-os/tree/main/kernel/net"
click node_apps "https://github.com/referefref/maytera-os/tree/main/userland/apps"
click node_browser "https://github.com/referefref/maytera-os/blob/main/userland/apps/browser/main.c"
click node_compat "https://github.com/referefref/maytera-os/tree/main/kernel/dos"
click node_media "https://github.com/referefref/maytera-os/tree/main/kernel/media"
click node_games "https://github.com/referefref/maytera-os/blob/main/userland/apps/squadron/main.c"
click node_boot "https://github.com/referefref/maytera-os/blob/main/boot/uefi/bootloader.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_assistant,node_toolclient,node_contracts,node_consent,node_capabilities,node_audit,node_user toneBlue
class node_compositor,node_window,node_settings,node_files toneAmber
class node_kernel,node_process,node_memory,node_services,node_boot toneMint
class node_vfs,node_filesystems,node_network toneRose
class node_apps,node_browser,node_compat,node_media,node_games toneIndigo
```

## Components

### Assistant and Safety

- [Maytera AI](https://github.com/referefref/maytera-os/blob/main/userland/apps/aichat/main.c): `userland/apps/aichat/main.c`
- [AI tool client](https://github.com/referefref/maytera-os/blob/main/userland/libc/aiclient.c): `userland/libc/aiclient.c`
- [App tool contracts](https://github.com/referefref/maytera-os/blob/main/userland/libc/contract.h): `userland/libc/contract.h`
- [Consent prompt](https://github.com/referefref/maytera-os/blob/main/kernel/gui/desktop.h): `kernel/gui/desktop.h`
- [Capability enforcement](https://github.com/referefref/maytera-os/blob/main/kernel/security/security.c): `kernel/security/security.c`
- [Action audit](https://github.com/referefref/maytera-os/blob/main/kernel/security/security.c): `kernel/security/security.c`

### Desktop Experience

- [Desktop compositor](https://github.com/referefref/maytera-os/blob/main/userland/apps/compositor/main.c): `userland/apps/compositor/main.c`
- [Window system](https://github.com/referefref/maytera-os/blob/main/kernel/gui/window.h): `kernel/gui/window.h`
- [Settings](https://github.com/referefref/maytera-os/tree/main/userland/apps): `userland/apps`
- [Files browser](https://github.com/referefref/maytera-os/blob/main/userland/apps/files/main.c): `userland/apps/files/main.c`

### Kernel and Runtime

- [Kernel core](https://github.com/referefref/maytera-os/blob/main/kernel/main.c): `kernel/main.c`
- [Process and scheduler](https://github.com/referefref/maytera-os/blob/main/kernel/proc/process.c): `kernel/proc/process.c`
- [Virtual memory](https://github.com/referefref/maytera-os/blob/main/kernel/mm/vmm.c): `kernel/mm/vmm.c`
- [Service lifecycle](https://github.com/referefref/maytera-os/blob/main/kernel/proc/services.c): `kernel/proc/services.c`
- [UEFI bootloader](https://github.com/referefref/maytera-os/blob/main/boot/uefi/bootloader.c): `boot/uefi/bootloader.c`

### Storage and Networking

- [Virtual filesystem](https://github.com/referefref/maytera-os/blob/main/kernel/fs/vfs.c): `kernel/fs/vfs.c`
- [ext2 and FAT](https://github.com/referefref/maytera-os/tree/main/kernel/fs): `kernel/fs`
- [Network and TLS](https://github.com/referefref/maytera-os/tree/main/kernel/net): `kernel/net`

### Applications and Compatibility

- [Native applications](https://github.com/referefref/maytera-os/tree/main/userland/apps): `userland/apps`
- [Web browser](https://github.com/referefref/maytera-os/blob/main/userland/apps/browser/main.c): `userland/apps/browser/main.c`
- [DOS and Win16](https://github.com/referefref/maytera-os/tree/main/kernel/dos): `kernel/dos`
- [Media playback](https://github.com/referefref/maytera-os/tree/main/kernel/media): `kernel/media`
- [Games](https://github.com/referefref/maytera-os/blob/main/userland/apps/squadron/main.c): `userland/apps/squadron/main.c`

### Other components

- **Desktop user**

## Connections

- Desktop user → Maytera AI: invokes
- Maytera AI → AI tool client: uses
- AI tool client → App tool contracts: exposes controls (evidence: `userland/libc/aiclient.c`)
- AI tool client → Consent prompt: requests approval
- Consent prompt → Capability enforcement: grants scope
- AI tool client → Action audit: records outcome
- Capability enforcement → Kernel core: gates syscalls
- Desktop user → Desktop compositor: interacts with
- Desktop compositor → Window system: manages windows
- Desktop user → Files browser: browses files
- Kernel core → Process and scheduler: schedules
- Kernel core → Virtual memory: provides paging
- Service lifecycle → Process and scheduler: starts services (evidence: `kernel/proc/services.c`)
- Virtual filesystem → ext2 and FAT: mounts
- Network and TLS → Web browser: fetches pages (evidence: `userland/apps/browser/main.c`)
- Desktop user → Native applications: launches
- Desktop user → DOS and Win16: runs supplied software
- Desktop user → Media playback: plays media
- Desktop user → Games: plays games
- UEFI bootloader → Kernel core: boots
