> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystems From First Principles

> What a filesystem actually is — files, inodes, and directories — and how a local one is implemented: a metadata index (inodes and bitmaps) over a region of data blocks.

CloudFS gives you a POSIX filesystem you mount on any host or container, backed by Telnyx Cloud Storage. To understand how it works — and why it is shaped the way it is — these Concepts pages build the idea from the bottom up:

1. **What a filesystem is and how a local one is built** (this page)
2. [Why past network filesystems fall short, and how the early cluster filesystems reframed storage](/docs/edge-compute/cloudfs/concepts/network-filesystems) (NFS and AFS → GFS, HDFS, MooseFS)
3. [How CloudFS puts it together](/docs/edge-compute/cloudfs/concepts/how-cloudfs-works)

The framing follows the standard treatment in [*Operating Systems: Three Easy Pieces*](https://pages.cs.wisc.edu/~remzi/OSTEP/) (OSTEP), by Remzi and Andrea Arpaci-Dusseau. It is worth reading in full; these pages borrow just enough to motivate the design.

## What a Filesystem Actually Is

Strip away the tooling and a filesystem is [two abstractions](https://pages.cs.wisc.edu/~remzi/OSTEP/file-intro.pdf):

* A **file** is a linear array of bytes with a **low-level name** — a number, the **inode number**. The operating system does not care whether those bytes are a JPEG or C source; it stores them and hands them back intact.
* A **directory** is itself a file, but its contents are specific: a list of `(human-readable name → inode number)` pairs. Nest directories inside directories and you get the tree you navigate every day.

So underneath a familiar path like `/home/agent/work.log`, a filesystem is really two things: **an index** that maps names to inodes and inodes to the location of bytes, and **the bytes themselves**. Everything else — `open`/`read`/`write`/`close`, permissions, hard and symbolic links — is built on top of those two.

## How a Local Filesystem Is Built

On a single disk, those two things live in two different places. OSTEP's teaching filesystem, [vsfs](https://pages.cs.wisc.edu/~remzi/OSTEP/file-implementation.pdf), divides the disk into an **inode table** plus small **bitmaps** that track which inodes and blocks are free — this is the metadata index — and a much larger **data region** of fixed-size blocks that holds file contents. Each inode is a compact record of metadata (permissions, timestamps, size) plus a **multi-level index** of pointers to the file's data blocks. Reading a file means reading its inode to find the block pointers, then reading the blocks; writing a file may also flip an allocation bit and rewrite the inode.

The [Fast File System](https://pages.cs.wisc.edu/~remzi/OSTEP/file-ffs.pdf) added the lesson that *where* you place those blocks matters: the original Unix filesystem treated the disk like RAM and paid for it in seeks, so FFS made the filesystem **"disk-aware"** — keep an inode near its data, keep files of one directory together, respect the physical medium.

The durable takeaway is this: **a filesystem is a metadata index over a pile of data blocks — two kinds of state with two very different access patterns.** Metadata is small, hot, and demands consistency: an inode is either allocated or it is not. Data is large and wants throughput. Hold onto that split; it is the key to everything that follows.

## Staying Consistent Across Crashes

The metadata index has one more demand: it must survive a crash. A single logical operation — appending a block to a file, say — touches several structures (the allocation bitmap, the inode, the data block), but the disk writes them one at a time. Lose power in between and the index is left inconsistent: a block marked used by no file, or an inode pointing at garbage.

Early filesystems repaired this after the fact with **fsck**, scanning the whole disk on reboot — which stops scaling as disks grow. The durable fix, [**journaling** (write-ahead logging)](https://pages.cs.wisc.edu/~remzi/OSTEP/file-journaling.pdf), is borrowed straight from databases: write your intended changes to a **log** and commit them there first, then apply them to their real homes; after a crash, replay the committed log. Recovery then costs the size of the log, not the size of the disk. Keep this one in mind — it is the cleanest argument for *where* CloudFS keeps its metadata.

And the medium underneath can lie: a sector rots, or silently returns the wrong bytes. Filesystems and storage layers defend against it with [checksums and scrubbing](https://pages.cs.wisc.edu/~remzi/OSTEP/file-integrity.pdf); CloudFS leaves that to the object store, which does it for you.

## Further Reading

* [*Operating Systems: Three Easy Pieces*](https://pages.cs.wisc.edu/~remzi/OSTEP/) — [Files and Directories](https://pages.cs.wisc.edu/~remzi/OSTEP/file-intro.pdf), [File System Implementation](https://pages.cs.wisc.edu/~remzi/OSTEP/file-implementation.pdf), [Locality and the Fast File System](https://pages.cs.wisc.edu/~remzi/OSTEP/file-ffs.pdf), [Crash Consistency: FSCK and Journaling](https://pages.cs.wisc.edu/~remzi/OSTEP/file-journaling.pdf), and [Data Integrity and Protection](https://pages.cs.wisc.edu/~remzi/OSTEP/file-integrity.pdf).

**Next:** [Network Filesystems: From NFS to GFS](/docs/edge-compute/cloudfs/concepts/network-filesystems) — what happens when you stretch this across a network.