PyOS Architecture

Technical reference for every module in the system. For beginner-friendly explanations with analogies, see the concept guides.

Design Principles

1. Mirror real OS architecture -- every module corresponds to a real OS subsystem.
2. TDD -- tests written first, then implementation, then refactoring.
3. Syscalls as the boundary -- the shell never touches kernel internals directly.
4. Returns strings, not prints -- everything is testable, no side effects.
5. Simplicity over performance -- clarity wins in a learning simulator.

System Overview

How all the layers fit together, from user commands down to hardware simulation.

graph TD
    subgraph User Space
        REPL[REPL / Web UI]
        Shell[Shell]
    end

    subgraph Syscall Boundary
        Syscalls[Syscall Dispatch]
    end

    subgraph Kernel
        K[Kernel Coordinator]
        Sched[Scheduler]
        Mem[Memory Manager]
        FS[Filesystem]
        Dev[Device Manager]
        Users[User Manager]
        Net[Networking]
        Sync[Sync Primitives]
        Proc[/proc Filesystem]
    end

    REPL --> Shell
    Shell --> Syscalls
    Syscalls --> K
    K --> Sched
    K --> Mem
    K --> FS
    K --> Dev
    K --> Users
    K --> Net
    K --> Sync
    K --> Proc

Boot Sequence

The chain of events from power-on to a working shell.

sequenceDiagram
    participant FW as Firmware
    participant BL as Bootloader
    participant K as Kernel
    participant S as Shell

    FW->>FW: POST (check memory, CPU)
    FW->>BL: Hand off control
    BL->>BL: Load kernel image
    BL->>K: boot()
    K->>K: Init scheduler
    K->>K: Init memory manager
    K->>K: Init filesystem
    K->>K: Init device manager
    K->>K: Init user manager
    K->>K: Spawn init process
    K->>K: State → RUNNING
    K->>S: Create shell
    S->>S: Ready for commands

Syscall Flow

What happens when you type a command in the shell.

sequenceDiagram
    participant U as User
    participant S as Shell
    participant SC as Syscall Dispatch
    participant K as Kernel
    participant Sub as Subsystem

    U->>S: Type command
    S->>S: Parse command + args
    S->>SC: kernel.syscall(number, **kwargs)
    SC->>SC: Validate kernel is running
    SC->>SC: Switch to kernel mode
    SC->>K: dispatch_syscall(number, **kwargs)
    K->>Sub: Route to handler
    Sub-->>K: Result
    K-->>SC: Return result
    SC-->>S: Return to user mode
    S-->>U: Display output

Module Dependency Graph

How the source modules import from each other.

graph LR
    shell[shell/] --> syscalls[syscalls.py]
    syscalls --> kernel[kernel.py]
    kernel --> scheduler[scheduler.py]
    kernel --> manager[manager.py]
    kernel --> filesystem[filesystem.py]
    kernel --> devices[devices.py]
    kernel --> users[users.py]
    kernel --> networking[networking.py]
    kernel --> tcp[tcp.py]
    kernel --> dns[dns.py]
    kernel --> interrupts[interrupts.py]
    kernel --> timer[timer.py]
    kernel --> procfs[procfs.py]
    kernel --> inheritance[inheritance.py]
    kernel --> ordering[ordering.py]
    kernel --> deadlock[deadlock.py]
    kernel --> primitives[primitives.py]
    kernel --> slab[slab.py]
    kernel --> swap[swap.py]
    kernel --> journal[journal.py]
    kernel --> shm[shm.py]
    kernel --> logging[logging.py]
    kernel --> containers[containers.py]
    kernel --> bridge[bridge.py]
    kernel --> binary[binary.py]
    manager --> virtual[virtual.py]
    filesystem --> fd[fd.py]
    repl[repl.py] --> bootloader[bootloader.py]
    repl --> shell
    tutorials[tutorials.py] --> syscalls

Concept Guides

Guide	Topics
What Is an OS?	Big picture, layered architecture, how PyOS works
Processes	PCB, five-state model, scheduler, multi-CPU, fork (COW), threads, execution, zombies, wait/waitpid
Memory	Frames/pages, virtual memory, page replacement, swap, copy-on-write, mmap, slab allocator
Filesystem	Inodes, path resolution, hard/symbolic links, persistence, journaling, /proc virtual filesystem
The Boot Chain	Firmware POST, bootloader, kernel image, init process, dmesg
Kernel and System Calls	Boot sequence, lifecycle, syscall dispatch, number ranges
The Shell	Commands, pipes, redirection, loops, scripting, jobs, history, aliases, tab completion, env
Devices and Networking	Device protocol, IPC, disk scheduling, sockets, DNS, HTTP
Interrupts and Timers	Interrupt controller, vectors, masking, timer, preemption
TCP: Reliable Delivery	Three-way handshake, flow control, congestion control, retransmission
Users and Safety	Permissions, signals, logging, deadlock
Synchronization	Mutex, semaphore, condition variable, reader-writer lock, race conditions, deadlock prevention
Framebuffer	Pixel-level graphics, shapes, and image display
TUI Dashboard	Live terminal dashboard for OS internals
Permissions	File ownership, permission bits, groups, ACLs
Binary Loader	Loading and running programs with exec
Containers	PID, mount, and network namespaces for isolation
Inter-Machine Networking	Bridges, clusters, cross-machine messaging
Interactive Tutorials	Guided hands-on lessons using real syscalls
Web UI	Browser-based terminal via Flask

Module Map

Every source file and what it implements.

Boot Layer

File	Class/Function	Purpose
bootloader.py	Bootloader	Simulated firmware + bootloader: POST, load kernel image, boot kernel
bootloader.py	BootStage	FIRMWARE / BOOTLOADER / KERNEL / USERSPACE stage enum
bootloader.py	PostResult	Frozen dataclass capturing POST check outcomes
bootloader.py	KernelImage	Frozen dataclass representing the kernel binary on disk
bootloader.py	BootError	Raised when the boot chain cannot continue

Kernel Layer

File	Class/Function	Purpose
kernel.py	Kernel	Central coordinator, boot/shutdown lifecycle, subsystem ownership
kernel.py	KernelState	SHUTDOWN / BOOTING / RUNNING / SHUTTING_DOWN state machine
kernel.py	ExecutionMode	USER / KERNEL privilege level (enforced at property access)
kernel.py	KernelModeError	Raised when user-mode code accesses a kernel-only resource
kernel.py	kernel_mode()	Context manager that switches to kernel mode and restores on exit
kernel.py	strace_enable() / strace_disable()	Enable/disable syscall tracing
kernel.py	strace_log() / strace_clear()	Read/clear the strace trace log
kernel.py	_sanitize_value()	Format values for strace display (truncation, callable/bytes placeholders)
syscalls.py	dispatch_syscall()	Trap handler -- routes syscall numbers to kernel subsystem handlers
kernel.py	dmesg()	Return the kernel boot log (like Linux dmesg)
kernel.py	init_pid	PID of the init process (root of process tree)
syscalls.py	SyscallNumber	IntEnum of all syscall numbers (1-247)
syscalls.py	SyscallError	User-facing exception wrapping internal errors
containers.py	ContainerManager	Lifecycle management for all containers
containers.py	Container	Isolated environment with PID, mount, and network namespaces
containers.py	PidNamespace / MountNamespace / NetworkNamespace	Per-container isolation primitives
containers.py	ContainerState	CREATED / RUNNING / STOPPED state machine
containers.py	ContainerError	Exception for container operation failures

Process Management

File	Class/Function	Purpose
process/pcb.py	Process	PCB with five-state model, program/output/exit_code, thread management, effective_priority for PI, performance timing (wait_time, cpu_time, response_time, turnaround_time)
process/pcb.py	ProcessState	NEW / READY / RUNNING / WAITING / TERMINATED
process/scheduler.py	Scheduler	Per-CPU ready queue management, dispatch using pluggable policy, context_switches counter
process/scheduler.py	MultiCPUScheduler	Wraps N per-CPU Schedulers with load balancing, CPU affinity, migration
process/scheduler.py	FCFSPolicy	First Come, First Served scheduling
process/scheduler.py	RoundRobinPolicy	Time-sliced scheduling with configurable quantum
process/scheduler.py	PriorityPolicy	Highest-priority-first scheduling with FIFO tiebreaker
process/scheduler.py	AgingPriorityPolicy	Priority scheduling with aging to prevent starvation
process/scheduler.py	MLFQPolicy	Multilevel Feedback Queue with demotion and boost
process/scheduler.py	CFSPolicy	Completely Fair Scheduler with weighted virtual runtime
process/threads.py	Thread	Lightweight execution unit within a process
process/signals.py	Signal	SIGKILL / SIGUSR1 / SIGUSR2 / SIGTERM / SIGCONT / SIGSTOP
process/signals.py	SignalAction	TERMINATE / STOP / CONTINUE / IGNORE default actions
process/signals.py	DEFAULT_ACTIONS	Maps every signal to its default action
process/signals.py	UNCATCHABLE	frozenset of signals that cannot have handlers (SIGKILL, SIGSTOP)
process/binary.py	BinaryLoader	Load and execute named programs (demo binaries)
process/binary.py	DEMO_PROGRAMS	Registry of built-in demo programs
process/binary.py	BinaryLoaderError	Exception for binary loader failures

Memory Management

File	Class/Function	Purpose
memory/manager.py	MemoryManager	Frame-based allocation with free set, page tables, and refcounting for COW
memory/virtual.py	VirtualMemory	Per-process address space with page table translation and COW fault handling
memory/mmap.py	MmapRegion	Frozen dataclass describing a memory-mapped file region
memory/mmap.py	MmapError	Exception for mmap operation failures
memory/slab.py	SlabAllocator	Registry of named slab caches backed by physical frames
memory/slab.py	SlabCache	Pool of slabs for one fixed object size, auto-grows
memory/slab.py	Slab	One physical frame divided into equal-sized object slots
memory/slab.py	SlabError	Exception for slab operation failures
memory/swap.py	SwapSpace	Key-value backing store for evicted pages
memory/swap.py	FIFOPolicy / LRUPolicy / ClockPolicy	Page replacement strategies
memory/swap.py	Pager	Demand paging orchestrator (page faults, eviction, swap I/O)

Filesystem

File	Class/Function	Purpose
fs/filesystem.py	FileSystem	Inode-based filesystem with path resolution, links, CRUD, and offset-based I/O
fs/filesystem.py	_Inode	Internal metadata record (type, size, data, children, link_count)
fs/filesystem.py	FileType	FILE / DIRECTORY / SYMLINK
fs/filesystem.py	MAX_SYMLINK_DEPTH	Loop detection limit (40, matching Linux SYMLOOP_MAX)
fs/fd.py	FdTable	Per-process table mapping fd numbers (>= 3) to open file descriptions
fs/fd.py	OpenFileDescription	Track an open file's path, mode, and current byte offset
fs/fd.py	FileMode	READ / WRITE / READ_WRITE access modes
fs/fd.py	SeekWhence	SET / CUR / END seek directions
fs/fd.py	FdError	Exception for file descriptor operation failures
fs/journal.py	JournaledFileSystem	Composition wrapper adding WAL logging to every filesystem mutation
fs/journal.py	Journal	Write-ahead log managing transactions (begin/append/commit/abort)
fs/journal.py	JournalOp	CREATE_FILE / CREATE_DIR / WRITE / WRITE_AT / DELETE / LINK / SYMLINK
fs/journal.py	TransactionState	ACTIVE / COMMITTED / ABORTED
fs/journal.py	JournalEntry	Single logged operation within a transaction
fs/journal.py	Transaction	Atomic unit grouping journal entries
fs/persistence.py	dump_filesystem()	Serialize filesystem to JSON
fs/persistence.py	load_filesystem()	Deserialize filesystem from JSON
fs/persistence.py	dump_journaled_filesystem()	Serialize journaled filesystem (fs + journal + checkpoint) to JSON
fs/persistence.py	load_journaled_filesystem()	Deserialize journaled filesystem from JSON
fs/procfs.py	ProcFilesystem	Virtual /proc filesystem generating content from live kernel state
fs/procfs.py	ProcError	Exception for /proc operation failures

User Space

File	Class/Function	Purpose
shell/__init__.py	Shell	The command interpreter: combines every command group below with the shell engine
shell/base.py	ShellBase	The engine: pipes, redirection (>, >>, <, 2>), scripting (if/else, while/for loops), job control, background execution (&), and the dispatch table built from each group's COMMANDS
shell/base.py	Redirections	Parsed I/O redirection operators from a command string
shell/commands/*.py	FileCommands, ProcessCommands, MemoryCommands, ...	One module per topic (basics, files, users, processes, memory, sync, devices, network, isolation, learn), each with its commands and a COMMANDS table
completer.py	Completer	Context-aware tab completion for commands, subcommands, paths, programs, env vars, signals
users.py	UserManager	User registry with auto-incrementing UIDs
users.py	FilePermissions	Per-file owner/other read/write permission bits
env.py	Environment	KEY=VALUE store with copy semantics
jobs.py	JobManager	Background/foreground job tracking with output capture

I/O and Networking

File	Class/Function	Purpose
io/devices.py	DeviceManager	Device registry with uniform read/write protocol
io/devices.py	NullDevice / ConsoleDevice / RandomDevice	Built-in devices
io/ipc.py	Pipe	Byte-stream channel (FIFO)
io/ipc.py	MessageQueue	Typed generic message queue
io/disk.py	DiskScheduler	Request queue with pluggable scheduling policy
io/disk.py	FCFSPolicy / SSTFPolicy / SCANPolicy / CSCANPolicy	Disk I/O scheduling strategies
io/shm.py	SharedMemorySegment	Named shared memory region (dataclass with frames, storage, attachments)
io/shm.py	SharedMemoryError	Exception for shared memory operation failures
io/dns.py	DnsResolver	Local phone book — register, look up, remove, list, flush hostname records
io/dns.py	DnsRecord	Frozen dataclass — one hostname-to-IP (A record) mapping
io/dns.py	DnsError	Exception for DNS operation failures
io/networking.py	SocketManager	Socket lifecycle, connection routing, data buffers
io/networking.py	Socket / SocketState	Endpoint with CREATED/BOUND/LISTENING/CONNECTED/CLOSED states
io/networking.py	SocketError	Exception for socket operation failures
io/http.py	HttpMethod	GET / POST request methods (StrEnum)
io/http.py	HttpStatus	200 OK / 400 / 404 / 500 status codes (IntEnum)
io/http.py	HttpRequest / HttpResponse	Frozen dataclasses for HTTP messages
io/http.py	HttpError	Exception for HTTP operation failures
io/http.py	format_request() / parse_request()	Serialize/deserialize HTTP requests
io/http.py	format_response() / parse_response()	Serialize/deserialize HTTP responses
io/interrupts.py	InterruptController	Manage interrupt vectors, handlers, and pending IRQs with priority-based servicing
io/interrupts.py	InterruptType	TIMER / IO / SOFTWARE interrupt categories (StrEnum)
io/interrupts.py	InterruptPriority	LOW / NORMAL / HIGH / CRITICAL priority levels (IntEnum)
io/interrupts.py	InterruptVector	Frozen dataclass describing a registered vector (number, type, priority)
io/interrupts.py	InterruptRequest	Frozen dataclass for a queued IRQ (vector, type, priority, data, timestamp)
io/interrupts.py	VECTOR_TIMER / VECTOR_IO_BASE	Well-known vector numbers (0 and 16)
io/timer.py	TimerDevice	Programmable interval timer — fires VECTOR_TIMER interrupt every N ticks
io/tcp.py	TcpState	11-state TCP connection state machine (StrEnum)
io/tcp.py	TcpFlag	SYN / ACK / FIN / RST segment flags (StrEnum)
io/tcp.py	TcpSegment	Frozen dataclass for a TCP segment (ports, seq/ack numbers, flags, window, payload)
io/tcp.py	TcpConnection	One endpoint: state machine, seq tracking, flow control, congestion control (slow start + AIMD), retransmission
io/tcp.py	TcpStack	Manage multiple TCP connections, listener queues, segment routing, retransmission ticks
io/bridge.py	NetworkBridge	In-memory packet routing between kernel instances
io/bridge.py	Cluster	High-level multi-kernel manager for inter-machine communication
io/bridge.py	Packet	Frozen dataclass for a network packet (src, dst, payload, type)
io/bridge.py	PacketType	DATA / DNS_QUERY / DNS_RESPONSE / PING / PONG packet types
io/bridge.py	BridgeError	Exception for bridge operation failures

Synchronization

File	Class/Function	Purpose
sync/inheritance.py	PriorityInheritanceManager	Coordinate priority inheritance across mutexes, prevent priority inversion
sync/primitives.py	Mutex	Mutual exclusion lock with owner tracking, FIFO wait queue, and waiters property
sync/primitives.py	Semaphore	Counting semaphore with optional max bound
sync/primitives.py	Condition	Condition variable (wait/notify) paired with a mutex
sync/primitives.py	ReadWriteLock	Reader-writer lock with writer-preference and batch reader wake
sync/primitives.py	SyncManager	Registry for all sync primitives (mutexes, semaphores, conditions, rwlocks)
sync/ordering.py	OrderingMode	STRICT / WARN / OFF enforcement modes for resource ordering
sync/ordering.py	OrderingViolation	Frozen dataclass recording a single ordering violation
sync/ordering.py	ResourceOrderingManager	Enforce resource acquisition ordering to prevent circular wait (deadlock prevention)

Observability

File	Class/Function	Purpose
logging.py	Logger	Ring buffer of structured log entries
logging.py	LogLevel	DEBUG / INFO / WARNING / ERROR (IntEnum)
sync/deadlock.py	ResourceManager	Banker's algorithm matrices, deadlock detection
repl.py	run()	Interactive terminal with bootloader chain and dynamic boot banner
repl.py	format_boot_log()	Format boot log messages into a displayable banner

Tutorials

File	Class/Function	Purpose
tutorials.py	TutorialRunner	Guided, hands-on lessons that use real syscalls with educational commentary
tutorials.py	list_lessons()	Return sorted list of available lesson names
tutorials.py	run(name)	Execute a single lesson by name
tutorials.py	run_all()	Execute every lesson in recommended order

Web Frontend

File	Class/Function	Purpose
web/app.py	create_app()	Flask application factory — boots kernel, creates shell, wires routes
web/app.py	main()	Console entry point for pyos-web development server
web/templates/index.html	—	Single-page terminal UI with dark theme
web/static/style.css	—	Dark terminal aesthetic (green on dark blue)
web/static/terminal.js	—	Command input, history (Up/Down), fetch API calls

Syscall Number Ranges

Range	Category
1-8	Process operations (create, terminate, list, fork, threads, wait, waitpid)
10-19	Filesystem operations (create, read, write, delete, list, open, close, read_fd, write_fd)
20	Memory info
21-23	Memory-mapped files (mmap, munmap, msync)
24-27	Slab allocator (create cache, alloc, free, info)
28	File descriptor seek
34-36	Link operations (link, symlink, readlink)
30-33	User operations (whoami, create, list, switch)
40-42	Device operations (read, write, list)
50	Logging
60-61	Signal operations (send, register handler)
70-73	Environment variables
80	System info
90	Deadlock detection
91-93	Deadlock prevention (resource ordering)
100-101	Process execution (exec, run)
110-119, 122-125	Synchronization (mutex, semaphore, condition, reader-writer lock)
120-121	Scheduler operations (policy switching, MLFQ boost)
130-133	Journal operations (status, checkpoint, recover, crash)
140-146	Shared memory IPC (create, attach, detach, destroy, write, read, list)
150-154	DNS operations (register, lookup, remove, list, flush)
160-168	Socket operations (create, bind, listen, connect, accept, send, recv, close, list)
170-171	/proc virtual filesystem (read, list)
172-173	Performance metrics (read, reset)
180-183	Strace operations (enable, disable, log, clear)
190-203	Kernel-mode helpers (shutdown, scheduler info, lstat, sync listing, fd listing, resource listing, PI status, ordering violations, destroy mutex, dispatch, process info, strace status)
210-211	Boot info (dmesg boot log, boot metadata)
220-224	Multi-CPU operations (cpu info, set/get affinity, balance, migrate)
230-235	Interrupt and timer operations (tick, interrupt list/mask/unmask, timer info/set interval)
240-247	TCP operations (connect, send, recv, close, info, list, listen, accept)

Strategy Pattern Usage

The Strategy pattern appears in three subsystems, always with the same structure: a mechanism (the manager class) delegates to a policy (a swappable protocol implementation).

Subsystem	Mechanism	Policies
CPU Scheduling	Scheduler	FCFSPolicy, RoundRobinPolicy, PriorityPolicy, AgingPriorityPolicy, MLFQPolicy, CFSPolicy
Page Replacement	Pager	FIFOPolicy, LRUPolicy, ClockPolicy
Disk Scheduling	DiskScheduler	FCFSPolicy, SSTFPolicy, SCANPolicy, CSCANPolicy