# aritrash/obisync architecture

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

## Overview

Obisync is an experimental bare-metal AArch64 operating system. Its visible runtime starts at the architecture boot entry, selects board information, and hands execution to shared kernel startup; documented startup stages then initialize memory and scheduler facilities. During operation, timer interrupts drive ITAS scheduling, which chooses tasks and switches execution and address spaces. Major documented branches include exception/IRQ handling, physical and virtual memory, and scheduler tracing; drivers, filesystem, and security are visible as Stage 2 subsystems, though their internals and some startup wiring were not sampled.

Main entry points: [`kernel/src/sst/mod.rs`](https://github.com/aritrash/obisync/blob/main/kernel/src/sst/mod.rs) (Stage 2 orchestration), [`kernel/src/arch/aarch64/mod.rs`](https://github.com/aritrash/obisync/blob/main/kernel/src/arch/aarch64/mod.rs) (Exception and IRQ handling), [`kernel/src/sst/memory.rs`](https://github.com/aritrash/obisync/blob/main/kernel/src/sst/memory.rs) (Memory startup), [`kernel/src/scheduler/policy.rs`](https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/policy.rs) (Scheduling policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and Platform"]
  node_entry["Boot entry<br/>[main.rs]"]
  node_board["Board configuration<br/>[platform.rs]"]
  node_common["Kernel startup<br/>[coresync.rs]"]
  node_exceptions["Exception and IRQ handling<br/>[mod.rs]"]
  node_gic["GIC control<br/>[gic.rs]"]
  node_early["Early UART<br/>[uart.rs]"]
  node_mmio["MMIO access<br/>[mmio.rs]"]
end

subgraph group_memory["Memory Management"]
  node_memory_stage["Memory startup<br/>[memory.rs]"]
  node_pmm[("Physical allocator<br/>[pmm.rs]")]
  node_heap["Kernel heap<br/>[heap.rs]"]
  node_vmm["Virtual memory<br/>[vmm.rs]"]
  node_address["Task address spaces<br/>[address_space.rs]"]
end

subgraph group_sched["ITAS Scheduler"]
  node_queue[("Task lifecycle<br/>[queue.rs]")]
  node_policy["Scheduling policy<br/>[policy.rs]"]
  node_tick["Tick enforcement<br/>[tick.rs]"]
  node_context["Context switching<br/>[context.rs]"]
  node_trace["Scheduler observability<br/>[trace.rs]"]
end

subgraph group_services["Kernel Services"]
  node_stage2["Stage 2 orchestration<br/>[mod.rs]"]
  node_diagnostics["Fault diagnostics<br/>[errors.rs]"]
  node_drivers["Drivers<br/>[drivers.rs]"]
  node_filesystem["Filesystem<br/>[filesystem.rs]"]
  node_security["Security services<br/>[security.rs]"]
end

node_hardware(("AArch64 hardware"))

node_hardware -->|"starts"| node_entry
node_entry -->|"sets board"| node_board
node_entry -->|"calls"| node_common
node_board -->|"provides UART base"| node_early
node_early -->|"accesses registers"| node_mmio
node_hardware -->|"raises IRQs"| node_exceptions
node_exceptions -->|"acknowledges IRQ"| node_gic
node_exceptions -->|"dispatches timer tick"| node_tick
node_common -->|"initializes"| node_memory_stage
node_memory_stage -->|"uses allocator"| node_pmm
node_memory_stage -->|"initializes"| node_heap
node_memory_stage -->|"initializes"| node_vmm
node_vmm -->|"allocates tables"| node_pmm
node_stage2 -->|"initializes"| node_address
node_stage2 -->|"initializes tasks"| node_queue
node_stage2 -->|"runs"| node_drivers
node_stage2 -->|"runs"| node_filesystem
node_stage2 -->|"runs"| node_security
node_tick -->|"requests decision"| node_policy
node_context -->|"selects next task"| node_policy
node_policy -->|"reads task state"| node_queue
node_context -->|"switches address space"| node_address
node_context -->|"switches task stacks"| node_queue
node_trace -->|"reads task metrics"| node_queue
node_trace -->|"reads score details"| node_policy
node_exceptions -.->|"fault handling"| node_diagnostics

click node_entry "https://github.com/aritrash/obisync/blob/main/kernel/src/main.rs"
click node_board "https://github.com/aritrash/obisync/blob/main/kernel/src/platform.rs"
click node_common "https://github.com/aritrash/obisync/blob/main/kernel/src/coresync.rs"
click node_exceptions "https://github.com/aritrash/obisync/blob/main/kernel/src/arch/aarch64/mod.rs"
click node_gic "https://github.com/aritrash/obisync/blob/main/kernel/src/arch/aarch64/gic.rs"
click node_early "https://github.com/aritrash/obisync/blob/main/kernel/src/early/uart.rs"
click node_mmio "https://github.com/aritrash/obisync/blob/main/kernel/src/arch/aarch64/mmio.rs"
click node_memory_stage "https://github.com/aritrash/obisync/blob/main/kernel/src/sst/memory.rs"
click node_pmm "https://github.com/aritrash/obisync/blob/main/kernel/src/mm/pmm.rs"
click node_heap "https://github.com/aritrash/obisync/blob/main/kernel/src/mm/heap.rs"
click node_vmm "https://github.com/aritrash/obisync/blob/main/kernel/src/mm/vmm.rs"
click node_address "https://github.com/aritrash/obisync/blob/main/kernel/src/mm/address_space.rs"
click node_queue "https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/queue.rs"
click node_policy "https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/policy.rs"
click node_tick "https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/tick.rs"
click node_context "https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/context.rs"
click node_trace "https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/trace.rs"
click node_stage2 "https://github.com/aritrash/obisync/blob/main/kernel/src/sst/mod.rs"
click node_diagnostics "https://github.com/aritrash/obisync/blob/main/kernel/src/errors.rs"
click node_drivers "https://github.com/aritrash/obisync/blob/main/kernel/src/sst/drivers.rs"
click node_filesystem "https://github.com/aritrash/obisync/blob/main/kernel/src/sst/filesystem.rs"
click node_security "https://github.com/aritrash/obisync/blob/main/kernel/src/sst/security.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_entry,node_board,node_common,node_exceptions,node_gic,node_early,node_mmio toneBlue
class node_memory_stage,node_pmm,node_heap,node_vmm,node_address toneAmber
class node_queue,node_policy,node_tick,node_context,node_trace toneMint
class node_stage2,node_diagnostics,node_drivers,node_filesystem,node_security toneRose
class node_hardware toneIndigo
```

## Components

### Boot and Platform

- [Boot entry](https://github.com/aritrash/obisync/blob/main/kernel/src/main.rs): `kernel/src/main.rs`
- [Board configuration](https://github.com/aritrash/obisync/blob/main/kernel/src/platform.rs): `kernel/src/platform.rs`
- [Kernel startup](https://github.com/aritrash/obisync/blob/main/kernel/src/coresync.rs): `kernel/src/coresync.rs`
- [Exception and IRQ handling](https://github.com/aritrash/obisync/blob/main/kernel/src/arch/aarch64/mod.rs): `kernel/src/arch/aarch64/mod.rs`
- [GIC control](https://github.com/aritrash/obisync/blob/main/kernel/src/arch/aarch64/gic.rs): `kernel/src/arch/aarch64/gic.rs`
- [Early UART](https://github.com/aritrash/obisync/blob/main/kernel/src/early/uart.rs): `kernel/src/early/uart.rs`
- [MMIO access](https://github.com/aritrash/obisync/blob/main/kernel/src/arch/aarch64/mmio.rs): `kernel/src/arch/aarch64/mmio.rs`

### Memory Management

- [Memory startup](https://github.com/aritrash/obisync/blob/main/kernel/src/sst/memory.rs): `kernel/src/sst/memory.rs`
- [Physical allocator](https://github.com/aritrash/obisync/blob/main/kernel/src/mm/pmm.rs): `kernel/src/mm/pmm.rs`
- [Kernel heap](https://github.com/aritrash/obisync/blob/main/kernel/src/mm/heap.rs): `kernel/src/mm/heap.rs`
- [Virtual memory](https://github.com/aritrash/obisync/blob/main/kernel/src/mm/vmm.rs): `kernel/src/mm/vmm.rs`
- [Task address spaces](https://github.com/aritrash/obisync/blob/main/kernel/src/mm/address_space.rs): `kernel/src/mm/address_space.rs`

### ITAS Scheduler

- [Task lifecycle](https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/queue.rs): `kernel/src/scheduler/queue.rs`
- [Scheduling policy](https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/policy.rs): `kernel/src/scheduler/policy.rs`
- [Tick enforcement](https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/tick.rs): `kernel/src/scheduler/tick.rs`
- [Context switching](https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/context.rs): `kernel/src/scheduler/context.rs`
- [Scheduler observability](https://github.com/aritrash/obisync/blob/main/kernel/src/scheduler/trace.rs): `kernel/src/scheduler/trace.rs`

### Kernel Services

- [Stage 2 orchestration](https://github.com/aritrash/obisync/blob/main/kernel/src/sst/mod.rs): `kernel/src/sst/mod.rs`
- [Fault diagnostics](https://github.com/aritrash/obisync/blob/main/kernel/src/errors.rs): `kernel/src/errors.rs`
- [Drivers](https://github.com/aritrash/obisync/blob/main/kernel/src/sst/drivers.rs): `kernel/src/sst/drivers.rs`
- [Filesystem](https://github.com/aritrash/obisync/blob/main/kernel/src/sst/filesystem.rs): `kernel/src/sst/filesystem.rs`
- [Security services](https://github.com/aritrash/obisync/blob/main/kernel/src/sst/security.rs): `kernel/src/sst/security.rs`

### Other components

- **AArch64 hardware**

## Connections

- AArch64 hardware → Boot entry: starts
- Boot entry → Board configuration: sets board
- Boot entry → Kernel startup: calls
- Board configuration → Early UART: provides UART base
- Early UART → MMIO access: accesses registers
- AArch64 hardware → Exception and IRQ handling: raises IRQs
- Exception and IRQ handling → GIC control: acknowledges IRQ
- Exception and IRQ handling → Tick enforcement: dispatches timer tick
- Kernel startup → Memory startup: initializes
- Memory startup → Physical allocator: uses allocator
- Memory startup → Kernel heap: initializes
- Memory startup → Virtual memory: initializes
- Virtual memory → Physical allocator: allocates tables
- Stage 2 orchestration → Task address spaces: initializes
- Stage 2 orchestration → Task lifecycle: initializes tasks
- Stage 2 orchestration → Drivers: runs
- Stage 2 orchestration → Filesystem: runs
- Stage 2 orchestration → Security services: runs
- Tick enforcement → Scheduling policy: requests decision
- Context switching → Scheduling policy: selects next task
- Scheduling policy → Task lifecycle: reads task state
- Context switching → Task address spaces: switches address space
- Context switching → Task lifecycle: switches task stacks
- Scheduler observability → Task lifecycle: reads task metrics
- Scheduler observability → Scheduling policy: reads score details
- Exception and IRQ handling → Fault diagnostics: fault handling