# sweets/hummingbird architecture

> Architecture diagram of the GitHub repository sweets/hummingbird, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sweets/hummingbird
- Repository: https://github.com/sweets/hummingbird

## Overview

##### Project type and purpose
- This is a minimal, lightning-fast Linux init system written in C. It replaces traditional init systems (like sysvinit, runit, or systemd) by providing only the essential “start” and “stop” functionality via three sequential runlevels: fs, interlude, and tty.

##### File structure
- Top-level binaries (bin/): reboot and shutdown wrappers.
- dist/: distribution-specific runlevel scripts and libraries under kiss/ and trajan/.
- src/: core C source files (hummingbird.c, init.c, shutdown.c, signal.c) and headers.
- usr/lib/hummingbird/: installed runtime libraries and scripts for each runlevel.
- Makefile, Travis CI config, LICENSE, README: build, test, and metadata.

##### README for additional insights
- Describes three runlevels:
- fs: after mounting pseudo-filesystems
- interlude: before spawning ttys
- tty: launching terminal sessions
- Installation replaces /usr/lib/hummingbird with dist/<distro> snapshots.

a. Main components
- Bootloader & Kernel
- Init binary (hummingbird)
- Runlevel directories: fs, interlude, tty, each containing scripts and rc.lib
- Signal handler and shutdown logic
- Wrapper binaries (reboot, shutdown)
- Distribution-specific overlays (dist/)

b. Relationships and interactions
1. Bootloader → Kernel: hand-off to PID 1
2. Kernel → /sbin/init (hummingbird): invoked as PID 1
3. Init core reads configuration or default /usr/lib/hummingbird/*
4. Init forks/execs all scripts in fs/, waits for completion
5. Init forks/execs all scripts in interlude/, waits
6. Init forks/execs all scripts in tty/, launches getty processes
7. Signal handling: on SIGTERM or wrapper binaries, invoke shutdown sequence in reverse order or call shutdown.c
8. Shutdown: kill children, unmount, power-off

c. Architectural patterns / design principles
- Linear runlevels (simple pipeline)
- Modular script directories for distribution overrides
- Single-threaded core with fork/exec model (POSIX compliance)
- Minimal dependencies (C stdlib only)

d. Relevant technologies
- C99 codebase (gcc, clang, TCC compatible)
- POSIX fork/exec, signal APIs
- /sbin/init replacement

##### Detailed breakdown for the engineer
- Layer 1: Bootloader & Kernel (annotate where /sbin/init is invoked)
- Layer 2: Init core
- hummingbird.c: main loop
- init.c: argument parsing, path resolution
- signal.c: catch SIGTERM & SIGINT
- shutdown.c: teardown logic
- Layer 3: Runlevels (modular script execution)
- fs/ → mount-dependent services
- interlude/ → pre-TTY tasks
- tty/ → getty spawn
- rc.lib → shared helper functions
- Layer 4: Wrappers & distribution overlays
- bin/reboot & bin/shutdown call hummingbird’s shutdown path
- dist/<distro> replaces /usr/lib/hummingbird at install time

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Boot Sequence
    subgraph "Boot Sequence"
        direction TB
        Bootloader["Bootloader"]:::kernel
        Kernel["Kernel"]:::kernel
    end
    Bootloader --> Kernel
    Kernel --> InitCore

    %% Layer 2: Init Core
    subgraph "PID 1: hummingbird Core"
        direction TB
        InitCore["PID 1: hummingbird (hummingbird.c)"]:::core
        ArgParse["Argument Parsing & Path Resolution (init.c)"]:::core
        SignalHandler["Signal Handler (signal.c)"]:::core
        ShutdownLogic["Shutdown Logic (shutdown.c)"]:::core
    end
    InitCore --> ArgParse
    InitCore --> SignalHandler
    SignalHandler --> ShutdownLogic

    %% Layer 3: Runlevels
    subgraph "Runlevels"
        direction TB
        FS["Runlevel: fs"]:::runlevel
        Interlude["Runlevel: interlude"]:::runlevel
        TTY["Runlevel: tty"]:::runlevel
    end
    ShutdownLogic --> FS
    FS --> Interlude
    Interlude --> TTY

    %% Layer 4: Wrappers & Shutdown Trigger
    subgraph "Wrappers"
        direction TB
        Reboot["Wrapper: /sbin/reboot"]:::wrapper
        ShutdownWrapper["Wrapper: /sbin/shutdown"]:::wrapper
    end
    Reboot --> SignalHandler
    ShutdownWrapper --> SignalHandler

    %% Layer 5: Distribution Overlays
    subgraph "Distribution Overlays"
        direction TB
        subgraph "dist/kiss"
            KISS_fs["fs"]:::overlay
            KISS_interlude["interlude"]:::overlay
            KISS_tty["tty"]:::overlay
            KISS_rc["rc.lib"]:::overlay
            KISS_shutdown["shutdown"]:::overlay
        end
        subgraph "dist/trajan"
            TRAJ_fs["fs"]:::overlay
            TRAJ_interlude["interlude"]:::overlay
            TRAJ_tty["tty"]:::overlay
            TRAJ_rc["rc.lib"]:::overlay
            TRAJ_shutdown["shutdown"]:::overlay
        end
    end
    KISS_fs --> FS
    TRAJ_fs --> FS

    %% Layer 6: Installed Runtime
    subgraph "Installed Runtime (/usr/lib/hummingbird)"
        direction TB
        InstFS["fs"]:::runlevel
        InstTTY["tty"]:::runlevel
        InstShutdown["shutdown"]:::runlevel
    end
    KISS_fs --> InstFS
    TRAJ_fs --> InstFS
    KISS_tty --> InstTTY
    TRAJ_tty --> InstTTY
    KISS_shutdown --> InstShutdown
    TRAJ_shutdown --> InstShutdown

    %% Layer 7: Build & CI
    subgraph "Build & CI"
        direction TB
        MakefileNode["Makefile"]:::ci
        Travis[".travis.yml"]:::ci
    end

    %% Layer 8: Metadata & Docs
    subgraph "Metadata & Docs"
        direction TB
        Readme["README.md"]:::docs
        License["LICENSE"]:::docs
    end

    %% Click Events
    click InitCore "https://github.com/sweets/hummingbird/blob/master/src/hummingbird.c"
    click ArgParse "https://github.com/sweets/hummingbird/blob/master/src/init.c"
    click SignalHandler "https://github.com/sweets/hummingbird/blob/master/src/signal.c"
    click ShutdownLogic "https://github.com/sweets/hummingbird/blob/master/src/shutdown.c"
    click Reboot "https://github.com/sweets/hummingbird/tree/master/bin/reboot"
    click ShutdownWrapper "https://github.com/sweets/hummingbird/tree/master/bin/shutdown"
    click KISS_fs "https://github.com/sweets/hummingbird/tree/master/dist/kiss/fs"
    click KISS_interlude "https://github.com/sweets/hummingbird/tree/master/dist/kiss/interlude"
    click KISS_tty "https://github.com/sweets/hummingbird/tree/master/dist/kiss/tty"
    click KISS_rc "https://github.com/sweets/hummingbird/blob/master/dist/kiss/rc.lib"
    click KISS_shutdown "https://github.com/sweets/hummingbird/tree/master/dist/kiss/shutdown"
    click TRAJ_fs "https://github.com/sweets/hummingbird/tree/master/dist/trajan/fs"
    click TRAJ_interlude "https://github.com/sweets/hummingbird/tree/master/dist/trajan/interlude"
    click TRAJ_tty "https://github.com/sweets/hummingbird/tree/master/dist/trajan/tty"
    click TRAJ_rc "https://github.com/sweets/hummingbird/blob/master/dist/trajan/rc.lib"
    click TRAJ_shutdown "https://github.com/sweets/hummingbird/tree/master/dist/trajan/shutdown"
    click InstFS "https://github.com/sweets/hummingbird/tree/master/usr/lib/hummingbird/fs"
    click InstTTY "https://github.com/sweets/hummingbird/tree/master/usr/lib/hummingbird/tty"
    click InstShutdown "https://github.com/sweets/hummingbird/tree/master/usr/lib/hummingbird/shutdown"
    click MakefileNode "https://github.com/sweets/hummingbird/tree/master/Makefile"
    click Travis "https://github.com/sweets/hummingbird/blob/master/.travis.yml"
    click Readme "https://github.com/sweets/hummingbird/blob/master/README.md"
    click License "https://github.com/sweets/hummingbird/tree/master/LICENSE"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef runlevel fill:#98FB98,stroke:#333,stroke-width:1px
    classDef wrapper fill:#FFA500,stroke:#333,stroke-width:1px
    classDef overlay fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef kernel fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef ci fill:#F0F8FF,stroke:#333,stroke-width:1px
    classDef docs fill:#F5F5F5,stroke:#333,stroke-width:1px
```
