SparkOS/ARCHITECTURE.md

SparkOS Architecture

Overview

SparkOS is designed as a minimal Linux distribution with a custom init system and a modular architecture that allows for future expansion.

System Components

1. Init System (/sbin/init)

The init system is the first process started by the kernel (PID 1). It is responsible for:

• Mounting filesystems: proc, sys, dev, tmp
• Network initialization: Bringing up wired networking via DHCP
• Process management: Spawning and respawning the shell
• Signal handling: Reaping zombie processes
• System initialization: Setting up the initial environment

Implementation: src/init.c

• Written in C for minimal overhead
• Statically linked for independence
• ~100 lines of clean, well-documented code

2. Root Filesystem

Follows the Filesystem Hierarchy Standard (FHS):

/
├── bin/          Essential user binaries (busybox with symlinks)
├── sbin/         System binaries (init, mount, etc.)
├── etc/          System configuration files
├── proc/         Kernel process information (virtual)
├── sys/          Kernel system information (virtual)
├── dev/          Device files (virtual)
├── tmp/          Temporary files
├── usr/
│   ├── bin/      Non-essential user binaries
│   ├── sbin/     Non-essential system binaries
│   ├── lib/      Libraries for /usr/bin and /usr/sbin
│   └── lib64/    64-bit libraries
├── var/          Variable data (logs, caches)
├── root/         Root user home directory
└── home/         User home directories

3. Build System

Makefile: Main build orchestration

• make init: Compile init system
• make install: Install init to rootfs
• make image: Create bootable image (requires root)
• make clean: Clean build artifacts

Scripts:

• scripts/build.sh: Quick build for development
• scripts/setup_rootfs.sh: Create rootfs structure
• scripts/create_image.sh: Create dd-able disk image

4. Boot Process

Hardware Power-On
    ↓
BIOS/UEFI
    ↓
Bootloader (syslinux)
    ↓
Linux Kernel (vmlinuz)
    ↓
Init System (/sbin/init) [PID 1]
    ↓
Mount filesystems
    ↓
Initialize network (/sbin/init-network)
    ↓
Spawn busybox sh shell
    ↓
User interaction

Design Decisions

Why Custom Init?

• Simplicity: No dependencies, easy to understand
• Control: Full control over boot process
• Size: Minimal footprint (<1MB statically linked)
• Learning: Educational value for OS development

Why Static Linking?

• Independence: No library dependencies
• Portability: Works on any Linux system
• Reliability: No missing library issues

Why Busybox?

• Minimal: Single binary provides dozens of utilities
• Small footprint: Typically <1MB for full feature set
• Efficient: Less memory and storage overhead than full GNU coreutils
• Standard: De facto standard for embedded Linux systems
• Networking: Includes DHCP client (udhcpc), ping, wget, and network tools

Networking Strategy

SparkOS uses a two-phase networking approach:

Phase 1: Bootstrap (Wired Only)

• Wired networking configured via DHCP
• Automatic interface detection (eth0, enp0s3, etc.)
• DNS fallback to public servers (8.8.8.8, 1.1.1.1)
• Enables git clone to install spark CLI

Phase 2: Full Configuration (via spark CLI)

• WiFi configuration
• Advanced networking features
• Custom DNS settings
• Network profiles

Future Architecture

Planned Components

1. Qt6/QML GUI

   • Full-screen Wayland application
   • Android-like interface design
   • Desktop-oriented workflow

2. Wayland Compositor

   • Custom compositor for SparkOS
   • Minimal resource usage
   • Touch and mouse support

3. Spark CLI Tools (C++)

   • System management utilities
   • Package management
   • Network configuration (WiFi, VPN, etc.)
   • GUI launcher

4. Bootstrap Utilities (Included)

   • Git for cloning spark CLI
   • Sudo for proper privilege elevation
   • Busybox for core system utilities and networking

Security Considerations

• Static binaries reduce attack surface
• Minimal running processes
• Root filesystem can be read-only
• Future: sudo for privilege escalation
• Future: SELinux/AppArmor integration

Performance

• Fast boot time (seconds, not minutes)
• Low memory footprint (~50MB base system with busybox)
• No unnecessary background services
• Efficient init system

Portability

• AMD64 architecture (x86_64)
• dd-able disk images
• USB flash drive ready
• Future: ARM64 support

Extension Points

The architecture is designed for easy extension:

1. Init system: Can be enhanced with service management
2. Filesystem: Can add more mount points and partitions
3. Boot process: Can integrate other bootloaders
4. GUI: Clean separation allows GUI to be optional

Development Workflow

1. Modify source code in src/
2. Build with make init
3. Test init in isolation
4. Install to rootfs/ with make install
5. Create test image with sudo make image
6. Test on real hardware or VM

References

• Linux Kernel Documentation
• Filesystem Hierarchy Standard (FHS)
• POSIX Standards
• Qt6 Documentation
• Wayland Protocol Specification