# asmnajmussakibkhan/minivsfs-file-system-builder-and-adder architecture

> Architecture diagram of the GitHub repository asmnajmussakibkhan/minivsfs-file-system-builder-and-adder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asmnajmussakibkhan/minivsfs-file-system-builder-and-adder
- Repository: https://github.com/asmnajmussakibkhan/minivsfs-file-system-builder-and-adder

## Overview

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`](https://github.com/asmnajmussakibkhan/minivsfs-file-system-builder-and-adder/blob/main/mkfs_adder.c) (Adder), [`mkfs_builder.c`](https://github.com/asmnajmussakibkhan/minivsfs-file-system-builder-and-adder/blob/main/mkfs_builder.c) (Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tools["CLI tools"]
  node_mkfs_builder["Builder<br/>C CLI<br/>[mkfs_builder.c]"]
  node_mkfs_adder["Adder<br/>C CLI<br/>[mkfs_adder.c]"]
end

subgraph group_image["Disk image"]
  node_fs_image[("FS image<br/>binary container")]
  node_superblock["Superblock<br/>metadata"]
  node_inode_table["Inode table<br/>metadata"]
  node_bitmaps["Bitmaps<br/>allocation map"]
  node_root_dir["Root dir"]
  node_file_data["File data<br/>data blocks"]
  node_crc32(("CRC32<br/>integrity check"))
end

node_mkfs_builder -->|"create"| node_fs_image
node_mkfs_adder -->|"read/update"| node_fs_image
node_fs_image -->|"contains"| node_superblock
node_fs_image -->|"contains"| node_inode_table
node_fs_image -->|"contains"| node_bitmaps
node_fs_image -->|"contains"| node_root_dir
node_fs_image -->|"contains"| node_file_data
node_fs_image -.->|"protects"| node_crc32
node_mkfs_builder -->|"init"| node_superblock
node_mkfs_builder -->|"init"| node_inode_table
node_mkfs_builder -->|"init"| node_bitmaps
node_mkfs_builder -->|"init"| node_root_dir
node_mkfs_adder -->|"allocate"| node_inode_table
node_mkfs_adder -->|"allocate"| node_bitmaps
node_mkfs_adder -->|"write"| node_file_data
node_mkfs_adder -->|"link"| node_root_dir
node_mkfs_adder -.->|"refresh"| node_crc32

click node_mkfs_builder "https://github.com/asmnajmussakibkhan/minivsfs-file-system-builder-and-adder/blob/main/mkfs_builder.c"
click node_mkfs_adder "https://github.com/asmnajmussakibkhan/minivsfs-file-system-builder-and-adder/blob/main/mkfs_adder.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mkfs_builder,node_mkfs_adder toneBlue
class node_fs_image,node_superblock,node_inode_table,node_bitmaps,node_root_dir,node_file_data,node_crc32 toneAmber
```

## Components

### CLI tools

Standalone binaries that create and update filesystem images.

- [Builder](https://github.com/asmnajmussakibkhan/minivsfs-file-system-builder-and-adder/blob/main/mkfs_builder.c): C CLI · Creates a new blank MiniVSFS image with initial metadata and capacity limits. · `mkfs_builder.c`
- [Adder](https://github.com/asmnajmussakibkhan/minivsfs-file-system-builder-and-adder/blob/main/mkfs_adder.c): C CLI · Opens an existing image, adds one file, and writes a new updated image. · `mkfs_adder.c`

### Disk image

The binary filesystem container shared between the tools.

- **FS image**: binary container · On-disk MiniVSFS volume that stores metadata and file contents.
- **Superblock**: metadata · Top-level filesystem state and layout information.
- **Inode table**: metadata · Allocated inode records for files and directories.
- **Bitmaps**: allocation map · Tracks used and free inodes and data blocks.
- **Root dir**: directory · Top-level directory that anchors the filesystem namespace.
- **File data**: data blocks · Stored payload bytes for inserted files.
- **CRC32**: integrity check · Checksums used to validate critical on-disk structures.

## Connections

- 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.