# troglobit/finit architecture

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

## Overview

##### Project Type and Purpose
- This is “Finit”: a small, fast init system and process supervisor for Linux (written in C).
- Its core purpose is to replace SysV or systemd init: handle bootstrap tasks, parse configuration, start/stop services & one-shot tasks, supervise them, manage runlevels, cgroups, conditions, and expose a control API (`initctl`).

##### Key Architectural Elements (to be shown as separate components)
a. Bootstrap & Environment Setup
- Kernel hands off to `/sbin/init` → launches `finit`.
- Initial tasks: populate `/dev` via `udev` or `mdev`, set up `/run`, `/tmp`, mount filesystems (via built-in tmpfiles support).
b. Configuration Subsystem
- Parser for `/etc/finit.conf` and `/etc/finit.d/*.conf`.
- Environment files (e.g. `/etc/conf.d/…`).
- Tmpfiles.d integration (initial directory/file creation).
c. Core Event Loop & Scheduler
- Single-threaded event loop driving: runlevels, conditions, plugin hooks, service transitions.
- Runlevels state machine (S → 2 by default, 0 for halt, 6 for reboot).
d. Service Supervisor
- Starts services, tasks, run commands, SysV scripts.
- Monitors via PID files or sd_notify / s6 ready notifications.
- Restart logic on crash (respawn) based on runlevels and conditions.
e. Conditions & Dependency Manager
- Watches “conditions” (service PID files, network availability, custom cond files).
- Blocks/unblocks service start accordingly.
f. CGroup Manager
- Detects cgroups v2; assigns init, system, user, root groups.
- Organizes each service/process into its sub-cgroup.
g. Plugin Framework
- Loads dynamic libraries from `plugins/`.
- Exposes hook points throughout boot and runtime for extensibility (I/O, custom events).
h. Control Interface (`initctl`)
- UNIX domain socket or IPC channel.
- Commands: start/stop/reload services, runlevels, condition manipulation, status, logs, cgroup introspection.
i. Logging Integration
- Early-boot ring buffer logging (kernel log).
- Redirected logs via `logger` to syslog daemon once started.

##### External Dependencies & Interactions
- Kernel (signals for shutdown/halt, /sysfs for console detection).
- udev/mdev for `/dev` population.
- SysV scripts and third-party daemons (e.g. `syslogd`, `klogd`, NTP, getty).
- Filesystem layout: `/etc`, `/run/finit`, `/var/run`, `/tmpfiles.d`, `/cgroup/v2`.

##### Relationships and Data Flow
- Configuration → Core Event Loop → Scheduler decides when to invoke Service Supervisor.
- Service Supervisor spawns child processes; registers them for monitoring.
- Spawned services write PID files → Condition Manager picks up and signals readiness.
- Plugin Framework hooks into scheduler and runtime events (e.g. before/after service start).
- `initctl` communicates with the event loop through IPC to query status or change configuration at runtime.
- CGroup Manager intercepts service launch calls to set proper cgroup.

##### Architectural Patterns & Principles
- Reactor/Event-loop pattern to multiplex service events, timers, and IPC.
- Plugin architecture for decoupled extensibility.
- Declarative configuration driving imperative actions.
- Supervisory pattern for process monitoring and automatic restart.
- Run-to-completion vs. parallel vs. sequential tasks (run vs. task vs. service stanzas).

##### Technologies & Frameworks
- Language: ANSI C.
- Build: autotools (autogen.sh, configure.ac, Makefile.am).
- IPC: UNIX sockets (for `initctl`).
- OS features: POSIX signals, devtmpfs, cgroups v2, dynamic linker for plugins.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External dependencies
    Kernel["Linux Kernel"]:::external
    Udev["udev/mdev (/dev population)"]:::external
    SysV["SysV scripts & daemons"]:::external

    %% Data stores
    ConfFiles["/etc/finit.conf & /etc/finit.d/*.conf"]:::data
    EnvFiles["/etc/conf.d/"]:::data
    TmpfilesD["/tmpfiles.d/"]:::data
    CondDir["/run/finit/cond/"]:::data
    CgroupFS["/cgroup/v2 (cgroup v2 fs)"]:::data

    %% Core modules
    subgraph "Bootstrap & Environment Setup"
        direction TB
        Bootstrap["Bootstrap & Environment Setup"]:::core
    end

    subgraph "Configuration Subsystem"
        direction TB
        ConfigParser["Config Parser"]:::core
    end

    subgraph "Core Event Loop & Scheduler"
        direction TB
        EventLoop["Event Loop & Scheduler"]:::core
    end

    subgraph "Service Supervisor"
        direction TB
        Supervisor["Service Supervisor"]:::core
    end

    subgraph "Conditions & Dependency Manager"
        direction TB
        ConditionMgr["Condition Manager"]:::core
    end

    subgraph "CGroup Manager"
        direction TB
        CGroupMgr["CGroup Manager"]:::core
    end

    subgraph "Plugin Framework"
        direction TB
        PluginLoader["Plugin Loader & Hooks"]:::core
    end

    subgraph "Control Interface"
        direction TB
        InitctlIPC["initctl IPC Interface"]:::core
    end

    subgraph "Logging Integration"
        direction TB
        Logging["Logging Integration"]:::core
    end

    %% Flow arrows
    Kernel -->|boots| Bootstrap
    Udev -->|dev population| Bootstrap
    Bootstrap -->|mount/tmpfiles| ConfigParser

    ConfFiles -->|"parse configs"| ConfigParser
    EnvFiles -->|"load env files"| ConfigParser
    TmpfilesD -.->|"tmpfiles.d support"| Bootstrap

    ConfigParser -->|"configuration events"| EventLoop

    EventLoop -->|"invoke supervisor"| Supervisor
    EventLoop -->|"monitor conditions"| ConditionMgr
    EventLoop -->|"hook events"| PluginLoader
    EventLoop -->|"IPC commands"| InitctlIPC
    EventLoop -->|"log events"| Logging

    Supervisor -->|fork/exec          | Kernel
    Supervisor -->|register PID file  | ConditionMgr
    Supervisor -->|assign cgroup      | CGroupMgr

    ConditionMgr -->|"signal readiness"| EventLoop

    PluginLoader -.->|"HOOK_BOOT_* & HOOK_RUNTIME"| EventLoop

    InitctlIPC -->|"start/stop/status"| EventLoop

    Logging -->|early ring buffer| Kernel
    Logging -->|redirect via logger| SysV

    CGroupMgr -->|organize cgroups| CgroupFS

    SysV -->|legacy scripts| Supervisor

    %% Click events - Bootstrap & Environment Setup
    click Bootstrap "https://github.com/troglobit/finit/blob/master/src/finit.c"
    click Bootstrap "https://github.com/troglobit/finit/blob/master/src/devmon.c"
    click Bootstrap "https://github.com/troglobit/finit/blob/master/src/mount.c"
    click Bootstrap "https://github.com/troglobit/finit/blob/master/src/tmpfiles.c"
    click Bootstrap "https://github.com/troglobit/finit/tree/master/src/coldplug/"

    %% Click events - Configuration Subsystem
    click ConfigParser "https://github.com/troglobit/finit/blob/master/src/conf.c"
    click ConfigParser "https://github.com/troglobit/finit/blob/master/src/conf.h"
    click ConfigParser "https://github.com/troglobit/finit/blob/master/src/tmpfiles.c"
    click ConfigParser "https://github.com/troglobit/finit/blob/master/src/tmpfiles.h"
    click ConfigParser "https://github.com/troglobit/finit/tree/master/tmpfiles.d/"

    %% Click events - Core Event Loop & Scheduler
    click EventLoop "https://github.com/troglobit/finit/blob/master/src/sm.c"
    click EventLoop "https://github.com/troglobit/finit/blob/master/src/sm.h"
    click EventLoop "https://github.com/troglobit/finit/blob/master/src/schedule.c"
    click EventLoop "https://github.com/troglobit/finit/blob/master/src/schedule.h"
    click EventLoop "https://github.com/troglobit/finit/blob/master/src/keventd.c"

    %% Click events - Service Supervisor
    click Supervisor "https://github.com/troglobit/finit/blob/master/src/service.c"
    click Supervisor "https://github.com/troglobit/finit/blob/master/src/service.h"
    click Supervisor "https://github.com/troglobit/finit/blob/master/src/serv.c"
    click Supervisor "https://github.com/troglobit/finit/blob/master/src/serv.h"
    click Supervisor "https://github.com/troglobit/finit/blob/master/src/svc.c"
    click Supervisor "https://github.com/troglobit/finit/blob/master/src/svc.h"
    click Supervisor "https://github.com/troglobit/finit/blob/master/src/runparts.c"

    %% Click events - Conditions & Dependency Manager
    click ConditionMgr "https://github.com/troglobit/finit/blob/master/src/cond.c"
    click ConditionMgr "https://github.com/troglobit/finit/blob/master/src/cond.h"
    click ConditionMgr "https://github.com/troglobit/finit/blob/master/src/cond-w.c"

    %% Click events - CGroup Manager
    click CGroupMgr "https://github.com/troglobit/finit/blob/master/src/cgroup.c"
    click CGroupMgr "https://github.com/troglobit/finit/blob/master/src/cgroup.h"
    click CGroupMgr "https://github.com/troglobit/finit/blob/master/src/cgutil.c"
    click CGroupMgr "https://github.com/troglobit/finit/blob/master/src/cgutil.h"

    %% Click events - Plugin Framework
    click PluginLoader "https://github.com/troglobit/finit/blob/master/src/plugin.c"
    click PluginLoader "https://github.com/troglobit/finit/blob/master/src/plugin.h"
    click PluginLoader "https://github.com/troglobit/finit/tree/master/plugins/"

    %% Click events - Control Interface
    click InitctlIPC "https://github.com/troglobit/finit/blob/master/src/initctl.c"
    click InitctlIPC "https://github.com/troglobit/finit/blob/master/src/initctl.h"
    click InitctlIPC "https://github.com/troglobit/finit/blob/master/src/client.c"
    click InitctlIPC "https://github.com/troglobit/finit/blob/master/src/client.h"
    click InitctlIPC "https://github.com/troglobit/finit/tree/master/initctl/"

    %% Click events - Logging Integration
    click Logging "https://github.com/troglobit/finit/blob/master/src/log.c"
    click Logging "https://github.com/troglobit/finit/blob/master/src/log.h"
    click Logging "https://github.com/troglobit/finit/blob/master/src/logit.c"
    click Logging "https://github.com/troglobit/finit/blob/master/src/logrotate.c"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#1E88E5,stroke-width:2px
    classDef data fill:#C8E6C9,stroke:#388E3C,stroke-width:2px,shape:cylinder
    classDef external fill:#FFE0B2,stroke:#F57C00,stroke-width:2px
    class EventLoop,Supervisor,ConditionMgr,CGroupMgr,PluginLoader,InitctlIPC,ConfigParser,Bootstrap,Logging core
    class ConfFiles,EnvFiles,TmpfilesD,CondDir,CgroupFS data
    class Kernel,Udev,SysV external
    linkStyle default stroke:#9E9E9E,stroke-width:1px
    linkStyle 5,6,12 stroke-dasharray: 5 5,color:#616161
```
