SparkOS/ARCHITECTURE.md

SparkOS Architecture

Overview

SparkOS is a revolutionary operating system that uses the Linux kernel for hardware abstraction but ditches traditional Unix conventions. Instead of shells, users, and Unix utilities, SparkOS boots directly into a Qt6 GUI that interfaces with the kernel through standard Linux APIs.

Core Philosophy

1. No Unix Baggage: No user/group system, no shells, no Unix utilities by default
2. Direct Kernel Interface: GUI communicates directly with Linux kernel
3. Network-First: Networking is a primary interface, not an afterthought
4. GUI-Only: No CLI unless explicitly needed for debugging
5. Linux for Drivers: Leverage Linux's excellent hardware support

System Architecture

Boot Sequence:
Hardware → UEFI/BIOS → GRUB → Linux Kernel → init (PID 1) → Qt6 GUI

Stack Layers:
┌──────────────────────────────────────────┐
│         Qt6 GUI Application              │ ← User Interface
│    (sparkos-gui executable)              │
├──────────────────────────────────────────┤
│      Custom Init System (PID 1)          │ ← Process Manager
│    • Mounts filesystems                  │
│    • Spawns/respawns GUI                 │
│    • Reaps zombie processes              │
├──────────────────────────────────────────┤
│          Linux Kernel                    │ ← Hardware Abstraction
│    • All device drivers                  │
│    • Framebuffer driver                  │
│    • Input device drivers                │
│    • Network stack & drivers             │
│    • File system support                 │
├──────────────────────────────────────────┤
│            Hardware                      │
│    • Display, GPU, Input                 │
│    • Network adapters                    │
│    • Storage devices                     │
└──────────────────────────────────────────┘

Design Decisions

Why Ditch Unix Conventions?

Traditional Unix systems were designed for multi-user, time-sharing mainframes in the 1970s. Modern personal computing and embedded systems have different needs:

• Single User: Most devices have one user - authentication overhead is unnecessary
• GUI Primary: Modern users expect graphical interfaces, not command lines
• Network Central: Modern computing is network-centric, not file-centric
• Direct Access: Applications should talk directly to kernel, not through layers of abstraction

Why Keep Linux Kernel?

• Hardware Support: Linux has exceptional driver support for modern hardware
• Driver Abstraction: Well-tested, stable hardware abstraction layer
• Network Stack: Robust, high-performance networking
• File Systems: Mature support for various filesystems
• Security: SELinux, namespaces, cgroups for isolation
• Community: Active development and security updates

Why Qt6 GUI?

• Cross-Platform: Qt works on many platforms (future portability)
• Framebuffer Support: Can render directly to Linux framebuffer without X11/Wayland
• Modern: Native look and feel, hardware acceleration support
• Complete: Rich widget set, networking APIs, file I/O
• Performant: Efficient rendering and event handling

Why No X11/Wayland?

• Direct Rendering: Qt can render directly to framebuffer (/dev/fb0)
• Less Overhead: No display server running in between
• Simpler: Fewer processes, less memory usage
• Embedded-Friendly: Same approach used in embedded systems

Why Network-First?

Modern computing is inherently networked. Instead of treating networking as an add-on:

• Network APIs exposed directly to GUI
• Cloud storage as primary storage paradigm
• Web technologies integrated (future: embedded browser)
• Real-time updates and communication built-in

Future Architecture

Planned Components

1. Qt6/QML GUI

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

2. Wayland Compositor

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

3. Network Management

   • Qt6 NetworkManager integration
   • WiFi configuration UI
   • VPN and advanced networking UI

Security Considerations

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

Performance

• Fast boot time (seconds, not minutes)
• Low memory footprint (~20MB base init system)
• No unnecessary background services
• Efficient init system (no external dependencies)

Portability

• AMD64 (x86_64) and ARM64 (aarch64) architectures
• dd-able disk images
• USB flash drive ready
• Multi-architecture Docker images

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