# obstinix/pyxisos architecture

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

- Interactive diagram: https://gitdiagram.com/obstinix/pyxisos
- Repository: https://github.com/obstinix/pyxisos

## Overview

PyxisOS is a two-track operating-system project. The sampled runtime paths expose a working research-consensus CLI and prototypes for a native kernel; the README also documents an operational Arch-based desktop and management capabilities whose implementation files are not present in this tree. The main evidenced workflow accepts a query, routes it to agents, collects opinions, arbitrates a decision, and reports the result. Kernel and hardware components are shown as distinct runtime areas; unsampled wiring is omitted.

Main entry points: [`research/consensus/src/cli.ts`](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/cli.ts) (Consensus CLI), [`research/consensus/src/arbitration/decisionArbitrationLayer.ts`](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/arbitration/decisionArbitrationLayer.ts) (Decision Arbitration), [`native/lunar-core/src/main.rs`](https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/main.rs) (Lunar Core Entry), [`kernel/src/lib.rs`](https://github.com/obstinix/pyxisos/blob/main/kernel/src/lib.rs) (Kernel Library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consensus["Consensus Engine"]
  node_cli["Consensus CLI<br/>[cli.ts]"]
  node_router["Agent Router<br/>[router.ts]"]
  node_agentbase["Agent Contract<br/>[base.ts]"]
  node_researchagent["Research Agent<br/>[research.ts]"]
  node_logicagent["Logic Agent<br/>[logic.ts]"]
  node_securityagent["Security Agent<br/>[security.ts]"]
  node_provider["LLM Provider<br/>[provider.ts]"]
  node_anthropic["Anthropic Adapter"]
  node_arbitration["Decision Arbitration"]
  node_audit["Audit Logger<br/>[logger.ts]"]
end

subgraph group_kernel["Kernel Runtime"]
  node_scheduler["Task Scheduler<br/>[scheduler.rs]"]
  node_task["Task State<br/>[task.rs]"]
  node_ipc["IPC Channel<br/>[ipc.rs]"]
  node_sync["Spinlock<br/>[sync.rs]"]
  node_ffi["Kernel FFI<br/>[ffi.rs]"]
  node_kernelentry["Kernel Library<br/>[lib.rs]"]
end

subgraph group_hardware["Hardware and OS"]
  node_kernelmain["C Kernel Main<br/>[main.c]"]
  node_shell["Userspace Shell<br/>[shell.c]"]
  node_vfs["Virtual Filesystem<br/>[vfs.c]"]
  node_ramfs["RAM Filesystem<br/>[ramfs.c]"]
  node_memory["Memory Management<br/>[vmm.c]"]
  node_interrupts["Interrupt Handling<br/>[idt.c]"]
  node_drivers["Hardware Drivers<br/>[serial.c]"]
end

subgraph group_native["Native Track"]
  node_lunar["Lunar Core Entry<br/>[main.rs]"]
  node_nativeboot["Native Boot<br/>[mod.rs]"]
  node_nativememory["Native Memory<br/>[mod.rs]"]
  node_nativelog["Native Logging<br/>[logging.rs]"]
  node_nativepanic["Native Panic<br/>[panic.rs]"]
  node_aegis["Aegis Sandbox<br/>[lib.rs]"]
end

node_user(("Query User"))
node_decision["Decision Output"]
node_llmservice["Anthropic Service"]

node_user -->|"submits query"| node_cli
node_cli -->|"routes context"| node_router
node_cli -->|"registers agent"| node_researchagent
node_cli -->|"registers agent"| node_logicagent
node_cli -->|"registers agent"| node_securityagent
node_router -->|"accepts agents"| node_agentbase
node_cli -->|"dispatches analysis"| node_researchagent
node_cli -->|"dispatches analysis"| node_logicagent
node_cli -->|"dispatches analysis"| node_securityagent
node_researchagent -->|"sends prompt"| node_provider
node_cli -->|"arbitrates opinions"| node_arbitration
node_arbitration -->|"requests synthesis"| node_provider
node_arbitration -->|"logs opinions"| node_audit
node_arbitration -->|"logs outcome"| node_audit
node_arbitration -->|"returns decision"| node_decision
node_provider -.->|"implemented by"| node_anthropic
node_anthropic -.->|"calls API"| node_llmservice
node_scheduler -->|"updates tasks"| node_task
node_scheduler -->|"guards scheduler"| node_sync
node_ipc -->|"guards channel"| node_sync
node_kernelentry -->|"exports module"| node_scheduler
node_kernelentry -->|"exports module"| node_ipc
node_kernelentry -->|"exports module"| node_ffi
node_lunar -->|"initializes logging"| node_nativelog
node_lunar -->|"declares module"| node_nativeboot
node_lunar -->|"declares module"| node_nativememory
node_lunar -->|"declares module"| node_nativepanic

click node_cli "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/cli.ts"
click node_router "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/routing/router.ts"
click node_agentbase "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/agents/base.ts"
click node_researchagent "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/agents/research.ts"
click node_logicagent "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/agents/logic.ts"
click node_securityagent "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/agents/security.ts"
click node_provider "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/llm/provider.ts"
click node_anthropic "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/llm/anthropicProvider.ts"
click node_arbitration "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/arbitration/decisionArbitrationLayer.ts"
click node_audit "https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/audit/logger.ts"
click node_scheduler "https://github.com/obstinix/pyxisos/blob/main/kernel/src/scheduler.rs"
click node_task "https://github.com/obstinix/pyxisos/blob/main/kernel/src/task.rs"
click node_ipc "https://github.com/obstinix/pyxisos/blob/main/kernel/src/ipc.rs"
click node_sync "https://github.com/obstinix/pyxisos/blob/main/kernel/src/sync.rs"
click node_ffi "https://github.com/obstinix/pyxisos/blob/main/kernel/src/ffi.rs"
click node_kernelentry "https://github.com/obstinix/pyxisos/blob/main/kernel/src/lib.rs"
click node_kernelmain "https://github.com/obstinix/pyxisos/blob/main/kernel/core/main.c"
click node_shell "https://github.com/obstinix/pyxisos/blob/main/userspace/shell/shell.c"
click node_vfs "https://github.com/obstinix/pyxisos/blob/main/fs/vfs.c"
click node_ramfs "https://github.com/obstinix/pyxisos/blob/main/fs/ramfs.c"
click node_memory "https://github.com/obstinix/pyxisos/blob/main/mm/vmm.c"
click node_interrupts "https://github.com/obstinix/pyxisos/blob/main/arch/x86_64/cpu/idt.c"
click node_drivers "https://github.com/obstinix/pyxisos/blob/main/drivers/char/serial.c"
click node_lunar "https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/main.rs"
click node_nativeboot "https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/boot/mod.rs"
click node_nativememory "https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/memory/mod.rs"
click node_nativelog "https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/logging.rs"
click node_nativepanic "https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/panic.rs"
click node_aegis "https://github.com/obstinix/pyxisos/blob/main/native/aegis/src/lib.rs"

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_cli,node_router,node_agentbase,node_researchagent,node_logicagent,node_securityagent,node_provider,node_anthropic,node_arbitration,node_audit,node_user toneBlue
class node_scheduler,node_task,node_ipc,node_sync,node_ffi,node_kernelentry toneAmber
class node_kernelmain,node_shell,node_vfs,node_ramfs,node_memory,node_interrupts,node_drivers toneMint
class node_lunar,node_nativeboot,node_nativememory,node_nativelog,node_nativepanic,node_aegis toneRose
class node_decision,node_llmservice toneIndigo
```

## Components

### Consensus Engine

- [Consensus CLI](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/cli.ts): `research/consensus/src/cli.ts`
- [Agent Router](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/routing/router.ts): `research/consensus/src/routing/router.ts`
- [Agent Contract](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/agents/base.ts): `research/consensus/src/agents/base.ts`
- [Research Agent](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/agents/research.ts): `research/consensus/src/agents/research.ts`
- [Logic Agent](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/agents/logic.ts): `research/consensus/src/agents/logic.ts`
- [Security Agent](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/agents/security.ts): `research/consensus/src/agents/security.ts`
- [LLM Provider](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/llm/provider.ts): `research/consensus/src/llm/provider.ts`
- [Anthropic Adapter](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/llm/anthropicProvider.ts): `research/consensus/src/llm/anthropicProvider.ts`
- [Decision Arbitration](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/arbitration/decisionArbitrationLayer.ts): `research/consensus/src/arbitration/decisionArbitrationLayer.ts`
- [Audit Logger](https://github.com/obstinix/pyxisos/blob/main/research/consensus/src/audit/logger.ts): `research/consensus/src/audit/logger.ts`

### Kernel Runtime

- [Task Scheduler](https://github.com/obstinix/pyxisos/blob/main/kernel/src/scheduler.rs): `kernel/src/scheduler.rs`
- [Task State](https://github.com/obstinix/pyxisos/blob/main/kernel/src/task.rs): `kernel/src/task.rs`
- [IPC Channel](https://github.com/obstinix/pyxisos/blob/main/kernel/src/ipc.rs): `kernel/src/ipc.rs`
- [Spinlock](https://github.com/obstinix/pyxisos/blob/main/kernel/src/sync.rs): `kernel/src/sync.rs`
- [Kernel FFI](https://github.com/obstinix/pyxisos/blob/main/kernel/src/ffi.rs): `kernel/src/ffi.rs`
- [Kernel Library](https://github.com/obstinix/pyxisos/blob/main/kernel/src/lib.rs): `kernel/src/lib.rs`

### Hardware and OS

- [C Kernel Main](https://github.com/obstinix/pyxisos/blob/main/kernel/core/main.c): `kernel/core/main.c`
- [Userspace Shell](https://github.com/obstinix/pyxisos/blob/main/userspace/shell/shell.c): `userspace/shell/shell.c`
- [Virtual Filesystem](https://github.com/obstinix/pyxisos/blob/main/fs/vfs.c): `fs/vfs.c`
- [RAM Filesystem](https://github.com/obstinix/pyxisos/blob/main/fs/ramfs.c): `fs/ramfs.c`
- [Memory Management](https://github.com/obstinix/pyxisos/blob/main/mm/vmm.c): `mm/vmm.c`
- [Interrupt Handling](https://github.com/obstinix/pyxisos/blob/main/arch/x86_64/cpu/idt.c): `arch/x86_64/cpu/idt.c`
- [Hardware Drivers](https://github.com/obstinix/pyxisos/blob/main/drivers/char/serial.c): `drivers/char/serial.c`

### Native Track

- [Lunar Core Entry](https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/main.rs): `native/lunar-core/src/main.rs`
- [Native Boot](https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/boot/mod.rs): `native/lunar-core/src/boot/mod.rs`
- [Native Memory](https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/memory/mod.rs): `native/lunar-core/src/memory/mod.rs`
- [Native Logging](https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/logging.rs): `native/lunar-core/src/logging.rs`
- [Native Panic](https://github.com/obstinix/pyxisos/blob/main/native/lunar-core/src/panic.rs): `native/lunar-core/src/panic.rs`
- [Aegis Sandbox](https://github.com/obstinix/pyxisos/blob/main/native/aegis/src/lib.rs): `native/aegis/src/lib.rs`

### Other components

- **Query User**
- **Decision Output**
- **Anthropic Service**

## Connections

- Query User → Consensus CLI: submits query (evidence: `research/consensus/src/cli.ts`)
- Consensus CLI → Agent Router: routes context (evidence: `research/consensus/src/cli.ts`)
- Consensus CLI → Research Agent: registers agent (evidence: `research/consensus/src/cli.ts`)
- Consensus CLI → Logic Agent: registers agent (evidence: `research/consensus/src/cli.ts`)
- Consensus CLI → Security Agent: registers agent (evidence: `research/consensus/src/cli.ts`)
- Agent Router → Agent Contract: accepts agents (evidence: `research/consensus/src/routing/router.ts`)
- Consensus CLI → Research Agent: dispatches analysis (evidence: `research/consensus/src/cli.ts`)
- Consensus CLI → Logic Agent: dispatches analysis (evidence: `research/consensus/src/cli.ts`)
- Consensus CLI → Security Agent: dispatches analysis (evidence: `research/consensus/src/cli.ts`)
- Research Agent → LLM Provider: sends prompt (evidence: `research/consensus/src/agents/research.ts`)
- Consensus CLI → Decision Arbitration: arbitrates opinions (evidence: `research/consensus/src/cli.ts`)
- Decision Arbitration → LLM Provider: requests synthesis (evidence: `research/consensus/src/arbitration/decisionArbitrationLayer.ts`)
- Decision Arbitration → Audit Logger: logs opinions (evidence: `research/consensus/src/arbitration/decisionArbitrationLayer.ts`)
- Decision Arbitration → Audit Logger: logs outcome (evidence: `research/consensus/src/arbitration/decisionArbitrationLayer.ts`)
- Decision Arbitration → Decision Output: returns decision (evidence: `research/consensus/src/arbitration/decisionArbitrationLayer.ts`)
- LLM Provider → Anthropic Adapter: implemented by (evidence: `research/consensus/src/llm/anthropicProvider.ts`)
- Anthropic Adapter → Anthropic Service: calls API
- Task Scheduler → Task State: updates tasks (evidence: `kernel/src/scheduler.rs`)
- Task Scheduler → Spinlock: guards scheduler (evidence: `kernel/src/scheduler.rs`)
- IPC Channel → Spinlock: guards channel (evidence: `kernel/src/ipc.rs`)
- Kernel Library → Task Scheduler: exports module (evidence: `kernel/src/lib.rs`)
- Kernel Library → IPC Channel: exports module (evidence: `kernel/src/lib.rs`)
- Kernel Library → Kernel FFI: exports module (evidence: `kernel/src/lib.rs`)
- Lunar Core Entry → Native Logging: initializes logging (evidence: `native/lunar-core/src/main.rs`)
- Lunar Core Entry → Native Boot: declares module (evidence: `native/lunar-core/src/main.rs`)
- Lunar Core Entry → Native Memory: declares module (evidence: `native/lunar-core/src/main.rs`)
- Lunar Core Entry → Native Panic: declares module (evidence: `native/lunar-core/src/main.rs`)
