How asmnajmussakibkhan/minivsfs-file-system-builder-and-adder works
1. Repository purpose
- This repo is a tiny, two-tool implementation of a virtual filesystem called MiniVSFS.
- The architecture is centered on manipulating a disk image file rather than mounting a live filesystem.
2. Primary executables
- mkfs_builder.c: creates a new empty filesystem image.
- mkfs_adder.c: opens an existing image, inserts one file, and writes a new updated image.
- There are no services, daemons, or libraries beyond standard C runtime support.
3. Core architectural boundary: the image file
- The filesystem image is the main boundary and data store.
- Both tools treat the image as a binary container holding filesystem metadata and file contents.
- The image is the handoff point between tools: builder produces it, adder consumes and rewrites it.
4. Builder subsystem
- The builder initializes the on-disk structure from scratch.
- According to the README, it sets up the superblock, inode table, bitmaps, and root directory.
- Its output is a blank but valid MiniVSFS volume with integrity metadata such as CRC32.
5. Adder subsystem
- The adder reads an existing MiniVSFS image and integrates a new file into it.
- It allocates filesystem resources, specifically inodes and data blocks, then updates directory metadata.
- It produces a new image file rather than modifying the input in place, which is an important architectural detail.
6. Filesystem metadata flow
- The builder establishes the initial metadata layout.
- The adder updates that metadata as files are inserted.
- This implies a classic filesystem pipeline: allocate -> record inode -> write data -> update directory entry -> refresh checksums/metadata.
7. Integrity and validation
- CRC32 is a notable design feature and likely applies to critical filesystem structures or data areas.
- This means the repository is not just about storage layout, but also about maintaining consistency and detecting corruption.
8. Resource management model
- The project explicitly exposes two tunable capacities at creation time: image size and inode count.
- That suggests the filesystem is preallocated and bounded, with capacity decisions made up front by the builder.
- The adder must operate within those fixed limits when placing new files.
9. External interface
- Both programs are CLI tools compiled with GCC on Linux.
- User interaction is via command-line arguments such as image path, size, inode count, and input file path.
- There is no UI layer; the architecture is entirely batch-oriented and file-based.
10. Typical end-to-end data path
- A user first runs the builder to create out.img.
- Then the adder reads out.img, inserts a host file such as hello.txt, and writes out2.img.
- This sequence is the main workflow and should be the central flow in any architecture diagram.
11. What to show in a diagram
- Two standalone binaries on the left: builder and adder.
- A shared filesystem image format in the center.
- Inside the image, show metadata regions such as superblock, inode table, bitmaps, root directory, and file data.
- Add CRC32/integrity checks as a cross-cutting concern over the on-disk structures.
12. Overall shape of the system
- This is a single-purpose filesystem image generator/editor, not a general filesystem stack.
- The architecture is small, deterministic, and centered on binary serialization of filesystem structures into a file.
Main entry points: mkfs_adder.c Adder · mkfs_builder.c Builder
Components 9
CLI tools
Standalone binaries that create and update filesystem images.
Disk image
The binary filesystem container shared between the tools.
- FS image · On-disk MiniVSFS volume that stores metadata and file contents.
- Superblock · Top-level filesystem state and layout information.
- Inode table · Allocated inode records for files and directories.
- Bitmaps · Tracks used and free inodes and data blocks.
- Root dir · Top-level directory that anchors the filesystem namespace.
- File data · Stored payload bytes for inserted files.
- CRC32 · Checksums used to validate critical on-disk structures.
Connections 17
- Builder → FS image: create · Builds a new valid image from scratch.
- Adder → FS image: read/update · Consumes an existing image and writes a new updated image.
- FS image → Superblock: contains · The image stores filesystem layout metadata.
- FS image → Inode table: contains · The image stores inode records.
- FS image → Bitmaps: contains · The image stores allocation state.
- FS image → Root dir: contains · The image includes the root directory entry state.
- FS image → File data: contains · The image stores file contents in data blocks.
- FS image → CRC32: protects · Integrity checks apply to critical filesystem structures.
- Builder → Superblock: init · Initializes filesystem metadata layout.
- Builder → Inode table: init · Creates the initial inode table.
- Builder → Bitmaps: init · Seeds allocation bitmaps for an empty volume.
- Builder → Root dir: init · Creates the root directory.
- Adder → Inode table: allocate · Reserves an inode for the inserted file.
- Adder → Bitmaps: allocate · Marks blocks and inodes as used.
- Adder → File data: write · Places the new file payload into data blocks.
- Adder → Root dir: link · Adds or updates the directory entry for the inserted file.
- Adder → CRC32: refresh · Recomputes integrity data after modifications.