Skip to content

Architecture

FlatRoot is a single binary that resolves, downloads, extracts, and post-installs distro packages into an unprivileged rootfs directory. The pipeline runs as an ordered sequence of stages — backend selection, index fetch, seed assembly, dependency resolution, download, extraction, post-install scripts, and cache regeneration. Each stage returns a typed outcome consumed by the next stage or by the manifest writer.

The pipeline

Blue boxes are core pipeline stages. Purple boxes are post-install passes. Green is the output. Grey boxes are external inputs — the distribution mirror, the seed list assembled from user packages plus base and essential packages, and the local download cache.

  • Architecture / Spec / Specification — This section is the behavioural specification of FlatRoot: one page per use case, each recording what the tool promises for that request and how the promise travels through...
    architecture spec
  • Architecture / Spec / Exporting a Rootfs — A user names a finished rootfs and a destination and receives one compressed archive any ordinary tool can unpack — reproducible, faithful to symlinks, and free of the...
    architecture spec export
  • Architecture / Spec / Installing Packages — A user names a distribution, a release, a destination directory, and the packages they care about, and receives a complete root filesystem: the requested packages, everything...
    architecture spec install