# project-nirmala/source architecture

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

## Overview

This repository is a small x86-64 operating-system project with a Unix-like userland, kernel, and native C build tools. The boot workflow shown is Limine handoff into kernel initialization, memory and device setup, initrd filesystem mounting, and launch of `/sbin/init`. The tree also contains login/shell utilities, libc, a compiler, linker, make utility, and configuration tool. Edges are limited to calls visible in excerpts; unsampled subsystem wiring and userland startup relationships are not inferred.

Main entry points: [`sys/kern/main.c`](https://github.com/project-nirmala/source/blob/master/sys/kern/main.c) (Kernel startup), [`sys/fs/vfs.c`](https://github.com/project-nirmala/source/blob/master/sys/fs/vfs.c) (Virtual filesystem), [`bin/nircc/src/main.c`](https://github.com/project-nirmala/source/blob/master/bin/nircc/src/main.c) (C compiler), [`bin/nirld/src/main.c`](https://github.com/project-nirmala/source/blob/master/bin/nirld/src/main.c) (ELF linker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Kernel Boot"]
  node_kmain["Kernel startup<br/>[main.c]"]
  node_proc["Processes &amp; exec<br/>[proc.c]"]
  node_syscall["System calls<br/>[syscall.c]"]
end

subgraph group_hardware["Architecture &amp; Devices"]
  node_cpu["CPU setup<br/>[cpu.c]"]
  node_idt["Interrupt table<br/>[idt.c]"]
  node_pic["PIC controller<br/>[pic.c]"]
  node_serial["Serial console<br/>[serial.c]"]
  node_fbcon["Framebuffer console<br/>[fbcon.c]"]
end

subgraph group_storage["Memory &amp; Filesystems"]
  node_pmm["Physical memory<br/>[pmm.c]"]
  node_vmm["Virtual memory<br/>[vmm.c]"]
  node_kheap["Kernel heap<br/>[kheap.c]"]
  node_vfs["Virtual filesystem<br/>[vfs.c]"]
  node_lemonfs["Lemon filesystem<br/>[lemonfs.c]"]
end

subgraph group_userland["Userland &amp; libc"]
  node_init["Init process<br/>[init.c]"]
  node_libc["C library<br/>[stdio.c]"]
  node_login["Login<br/>[login.c]"]
  node_shell["Shell<br/>[sh.c]"]
end

subgraph group_toolchain["Build Tools"]
  node_nircc["C compiler<br/>[main.c]"]
  node_nirld["ELF linker<br/>[main.c]"]
  node_nirmake["Build executor<br/>[main.c]"]
  node_nirconfig["Config parser<br/>[nc_parse.c]"]
end

node_limine(("Limine bootloader"))

node_limine -->|"boots"| node_kmain
node_kmain -->|"initializes"| node_serial
node_kmain -->|"initializes"| node_idt
node_kmain -->|"initializes"| node_cpu
node_kmain -->|"initializes"| node_pmm
node_kmain -->|"initializes"| node_vmm
node_kmain -->|"initializes"| node_kheap
node_kmain -->|"initializes"| node_fbcon
node_kmain -->|"initializes"| node_pic
node_kmain -->|"mounts initrd"| node_vfs
node_kmain -->|"starts init"| node_proc
node_vfs -.-> node_lemonfs
node_kmain -->|"launches"| node_init
node_nircc -->|"preprocesses, parses, emits"| node_nircc
node_nirld -->|"links inputs"| node_nirld

click node_kmain "https://github.com/project-nirmala/source/blob/master/sys/kern/main.c"
click node_init "https://github.com/project-nirmala/source/blob/master/sbin/init/init.c"
click node_cpu "https://github.com/project-nirmala/source/blob/master/sys/arch/amd64/cpu.c"
click node_idt "https://github.com/project-nirmala/source/blob/master/sys/arch/amd64/idt.c"
click node_pic "https://github.com/project-nirmala/source/blob/master/sys/arch/amd64/pic.c"
click node_serial "https://github.com/project-nirmala/source/blob/master/sys/dev/serial.c"
click node_fbcon "https://github.com/project-nirmala/source/blob/master/sys/dev/fbcon.c"
click node_pmm "https://github.com/project-nirmala/source/blob/master/sys/vm/pmm.c"
click node_vmm "https://github.com/project-nirmala/source/blob/master/sys/vm/vmm.c"
click node_kheap "https://github.com/project-nirmala/source/blob/master/sys/vm/kheap.c"
click node_vfs "https://github.com/project-nirmala/source/blob/master/sys/fs/vfs.c"
click node_lemonfs "https://github.com/project-nirmala/source/blob/master/sys/fs/lemonfs.c"
click node_proc "https://github.com/project-nirmala/source/blob/master/sys/kern/proc.c"
click node_syscall "https://github.com/project-nirmala/source/blob/master/sys/kern/syscall.c"
click node_libc "https://github.com/project-nirmala/source/blob/master/lib/libc/stdio.c"
click node_login "https://github.com/project-nirmala/source/blob/master/bin/login/login.c"
click node_shell "https://github.com/project-nirmala/source/blob/master/bin/sh/sh.c"
click node_nircc "https://github.com/project-nirmala/source/blob/master/bin/nircc/src/main.c"
click node_nirld "https://github.com/project-nirmala/source/blob/master/bin/nirld/src/main.c"
click node_nirmake "https://github.com/project-nirmala/source/blob/master/bin/nirmake/src/main.c"
click node_nirconfig "https://github.com/project-nirmala/source/blob/master/tools/nirconfig/nc_parse.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_kmain,node_proc,node_syscall toneBlue
class node_cpu,node_idt,node_pic,node_serial,node_fbcon toneAmber
class node_pmm,node_vmm,node_kheap,node_vfs,node_lemonfs toneMint
class node_init,node_libc,node_login,node_shell toneRose
class node_nircc,node_nirld,node_nirmake,node_nirconfig,node_limine toneIndigo
```

## Components

### Kernel Boot

- [Kernel startup](https://github.com/project-nirmala/source/blob/master/sys/kern/main.c): `sys/kern/main.c`
- [Processes & exec](https://github.com/project-nirmala/source/blob/master/sys/kern/proc.c): `sys/kern/proc.c`
- [System calls](https://github.com/project-nirmala/source/blob/master/sys/kern/syscall.c): `sys/kern/syscall.c`

### Architecture & Devices

- [CPU setup](https://github.com/project-nirmala/source/blob/master/sys/arch/amd64/cpu.c): `sys/arch/amd64/cpu.c`
- [Interrupt table](https://github.com/project-nirmala/source/blob/master/sys/arch/amd64/idt.c): `sys/arch/amd64/idt.c`
- [PIC controller](https://github.com/project-nirmala/source/blob/master/sys/arch/amd64/pic.c): `sys/arch/amd64/pic.c`
- [Serial console](https://github.com/project-nirmala/source/blob/master/sys/dev/serial.c): `sys/dev/serial.c`
- [Framebuffer console](https://github.com/project-nirmala/source/blob/master/sys/dev/fbcon.c): `sys/dev/fbcon.c`

### Memory & Filesystems

- [Physical memory](https://github.com/project-nirmala/source/blob/master/sys/vm/pmm.c): `sys/vm/pmm.c`
- [Virtual memory](https://github.com/project-nirmala/source/blob/master/sys/vm/vmm.c): `sys/vm/vmm.c`
- [Kernel heap](https://github.com/project-nirmala/source/blob/master/sys/vm/kheap.c): `sys/vm/kheap.c`
- [Virtual filesystem](https://github.com/project-nirmala/source/blob/master/sys/fs/vfs.c): `sys/fs/vfs.c`
- [Lemon filesystem](https://github.com/project-nirmala/source/blob/master/sys/fs/lemonfs.c): `sys/fs/lemonfs.c`

### Userland & libc

- [Init process](https://github.com/project-nirmala/source/blob/master/sbin/init/init.c): `sbin/init/init.c`
- [C library](https://github.com/project-nirmala/source/blob/master/lib/libc/stdio.c): `lib/libc/stdio.c`
- [Login](https://github.com/project-nirmala/source/blob/master/bin/login/login.c): `bin/login/login.c`
- [Shell](https://github.com/project-nirmala/source/blob/master/bin/sh/sh.c): `bin/sh/sh.c`

### Build Tools

- [C compiler](https://github.com/project-nirmala/source/blob/master/bin/nircc/src/main.c): `bin/nircc/src/main.c`
- [ELF linker](https://github.com/project-nirmala/source/blob/master/bin/nirld/src/main.c): `bin/nirld/src/main.c`
- [Build executor](https://github.com/project-nirmala/source/blob/master/bin/nirmake/src/main.c): `bin/nirmake/src/main.c`
- [Config parser](https://github.com/project-nirmala/source/blob/master/tools/nirconfig/nc_parse.c): `tools/nirconfig/nc_parse.c`

### Other components

- **Limine bootloader**

## Connections

- Limine bootloader → Kernel startup: boots (evidence: `sys/kern/main.c`)
- Kernel startup → Serial console: initializes (evidence: `sys/kern/main.c`)
- Kernel startup → Interrupt table: initializes (evidence: `sys/kern/main.c`)
- Kernel startup → CPU setup: initializes (evidence: `sys/kern/main.c`)
- Kernel startup → Physical memory: initializes (evidence: `sys/kern/main.c`)
- Kernel startup → Virtual memory: initializes (evidence: `sys/kern/main.c`)
- Kernel startup → Kernel heap: initializes (evidence: `sys/kern/main.c`)
- Kernel startup → Framebuffer console: initializes (evidence: `sys/kern/main.c`)
- Kernel startup → PIC controller: initializes (evidence: `sys/kern/main.c`)
- Kernel startup → Virtual filesystem: mounts initrd (evidence: `sys/kern/main.c`)
- Kernel startup → Processes & exec: starts init (evidence: `sys/kern/main.c`)
- Virtual filesystem → Lemon filesystem
- Kernel startup → Init process: launches (evidence: `sys/kern/main.c`)
- C compiler → C compiler: preprocesses, parses, emits (evidence: `bin/nircc/src/main.c`)
- ELF linker → ELF linker: links inputs (evidence: `bin/nirld/src/main.c`)
