docs: Add containers-storage-architecture.md

I'd find it really useful to have a document with the implementation
details of containers-storage (really just the overlay driver).

I started on this, using some of the source code.  Is there already

Signed-off-by: Colin Walters <[email protected]>

docs/containers-storage-architecture.md

@@ -0,0 +1,76 @@
+## containers-storage 1 "May 2024"
+
+## NAME
+containers-storage-architecture - The implementation of containers-storage 
+
+NOTE: These are implementation details subject to change. This document
+is intended to be used only as an aid for debugging and development
+of the containers-storage system. Do *not* directly access the filesystem
+components below from external code, only from the Go API.
+
+## DESCRIPTION
+The *containers/storage* library manages the following object types:
+
+- layer: A filesystem tree, along with metadata
+- image: A reference to a layer, along with metadata
+- container: A layer whose parent is an image
+
+## Layer storage
+
+### `overlay/`
+
+The `overlay/` directory contains a set of layers, named
+by their digest (note, this is the "diffid" or *uncompressed*
+digest, not the compressed one).
+
+### layer:
+
+A layer has the following components:
+
+- `diff/`: The expanded filesystem tree
+- `work/`: A directory used by `overlayfs` mounts
+- `merged/`: This will be a mount point when a layer is mounted.
+- `link`: A regular file; this contains a unique string for the layer; see `l/` below.
+- `lower`: Contains all the lower layer mounts separated by ":" and ordered from uppermost to lowermost layers.
+
+### `l/`: Layer shortlinks
+
+The`l` directory at the root there will be a symbolic link
+with that unique string pointing the "diff" directory for layers.
+The symbolic links are used to reference lower layers in the "lower"
+file and on mount. The links are used to shorten the total length
+of a layer reference without requiring changes to the layer identifier
+or root directory. Mounts are always done relative to root and
+referencing the symbolic links in order to ensure the number of
+lower directories can fit in a single page for making the mount
+syscall. A hard upper limit of 500 lower layers is enforced to ensure
+that mounts do not fail due to length.
+
+### `overlay-layers/`
+
+This directory contains metadata for layers.  
+
+#### `layers.lock`
+
+Lockfile protecting reads and writes to this directory.
+
+#### `${layerid}.tar-split.gz`
+
+Each layer will have a `${layerid}.tar-split.gz` file containing the
+original input tar stream without file content; this is necessary
+to be able to reconstruct the original tar stream exactly after
+a layer content has been unpacked into `diff/`.  More in
+<https://github.com/vbatts/tar-split>
+
+#### `layers.json`
+
+Global list of metadata associated with layers.
+
+#### `volatile-layers.json`
+
+Like `layers.json`, but used for layers which are defined not to
+persist across reboots.
+
+### storage.lock
+
+A cross-process lockfile, protecting overall layer state.