# waseque199/minivsfs-image-generator-using-c architecture

> Architecture diagram of the GitHub repository waseque199/minivsfs-image-generator-using-c, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/waseque199/minivsfs-image-generator-using-c
- Repository: https://github.com/waseque199/minivsfs-image-generator-using-c

## Overview

##### Project Type and Purpose
- This is a pair of command-line tools (mkfs_builder and mkfs_adder) written in C that implement a minimal filesystem (MiniVSFS) inside a raw disk image.
- mkfs_builder initializes an empty MiniVSFS image. mkfs_adder injects user files into an existing image.

##### File Structure
- Top-level files:
- mkfs_builder.c: CLI tool to build a new image
- mkfs_adder.c: CLI tool to add files to an image
- Base Files/: sample text files used for testing
- README.md: project description, data-layout, usage, algorithms
- No separate frontend/backend; it’s a self-contained, procedural C application.

##### Main Components
- User / Shell (invokes the CLI with flags and parameters)
- mkfs_builder (binary)
- Command-line Parser
- Superblock Initializer
- Bitmap Initializer (inode/data bitmaps)
- Inode Table Creator
- Root Directory Creator
- CRC32 Checksum Module
- Block Writer (writes raw blocks to the image file)
- mkfs_adder (binary)
- Command-line Parser
- Image Reader (reads Superblock + Bitmaps + Inodes)
- Allocation Manager (first-fit on bitmaps)
- Inode Updater
- Directory Entry Manager
- Data Writer (writes file data, block padding)
- Checksum Updater (CRC32 & XOR for dir entries)
- Disk Image File (filesystem.img, test.img, updated.img)
- Superblock (1 block)
- Inode Bitmap (1 block)
- Data Bitmap (1 block)
- Inode Table (N blocks)
- Data Region (M blocks)
- Host Filesystem (where the raw image and source files reside)

##### Relationships and Data Flow
- mkfs_builder
→ initializes each on-disk structure in order (SB → inode bitmap → data bitmap → inode table → data region)
→ writes to Disk Image File
- mkfs_adder
→ reads Disk Image File structures (SB, bitmaps, inode table)
→ finds free inode & blocks via Allocation Manager
→ writes file data into Data Region
→ updates Bitmaps & Inode Table & Directory Entries
→ recalculates and writes checksums
→ writes out updated Disk Image File
- The Disk Image File is the persistent component shared by both tools.

##### Architectural Patterns and Design Principles
- Procedural, module-based C code (each major responsibility lives in its own function set)
- Data laid out in fixed-offset, packed binary structures for portability
- First-fit allocation algorithm for bitmaps
- Single root directory (flat namespace)
- Checksum validation for safety (CRC32 for metadata, XOR for directory entries)

##### Relevant Technologies & Libraries
- C standard library (fopen/fread/fwrite, argc/argv parsing)
- CRC32 implementation (e.g. zlib or custom algorithm)
- POSIX-style file I/O
- #pragma pack for strict on-disk layouts
- hexdump/xxd for debugging

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User / Shell"]:::user

    subgraph "mkfs_builder (CLI Tool)"
        direction TB
        MB["mkfs_builder"]:::exe
        MB_P["Command-line Parser"]:::internal
        MB_SB["Superblock Initializer"]:::internal
        MB_IBM["Bitmap Initializer"]:::internal
        MB_IT["Inode Table Creator"]:::internal
        MB_RD["Root Directory Creator"]:::internal
        MB_CK["CRC32 Checksum Module"]:::internal
        MB_BW["Block Writer"]:::internal
    end

    subgraph "mkfs_adder (CLI Tool)"
        direction TB
        MA["mkfs_adder"]:::exe
        MA_P["Command-line Parser"]:::internal
        MA_IR["Image Reader"]:::internal
        MA_AM["Allocation Manager"]:::internal
        MA_IU["Inode Updater"]:::internal
        MA_DE["Directory Entry Manager"]:::internal
        MA_DW["Data Writer"]:::internal
        MA_CU["Checksum Updater"]:::internal
    end

    subgraph "Disk Image File"
        direction TB
        IMG["filesystem.img (RAW)"]:::storage
        SB[(Superblock)]:::ondisk
        IBM[(Inode Bitmap)]:::ondisk
        DBM[(Data Bitmap)]:::ondisk
        ITBL[(Inode Table)]:::ondisk
        DR[(Data Region)]:::ondisk
    end

    Base["Base Files/"]:::files
    README["README.md"]:::docs

    %% Relationships
    User -->|invokes| MB
    User -->|invokes| MA

    MB --> MB_P
    MB_P --> MB_SB
    MB_SB -->|write SB| SB
    MB_IBM -->|write inode bitmap| IBM
    MB_SB --> MB_IBM
    MB_IBM --> MB_IT
    MB_IT -->|write inode table| ITBL
    MB_IT --> MB_RD
    MB_RD -->|write root dir| DR
    MB_RD --> MB_CK
    MB_CK -->|checksum metadata| SB
    MB_CK --> MB_BW
    MB_BW -->|flush blocks to image| IMG

    MA --> MA_P
    MA_P --> MA_IR
    MA_IR -->|read SB| SB
    MA_IR -->|read inode bitmap| IBM
    MA_IR -->|read data bitmap| DBM
    MA_IR -->|read inode table| ITBL
    MA_IR --> MA_AM
    MA_AM -->|allocate blocks/inodes| IBM
    MA_AM -->|allocate blocks/inodes| DBM
    MA_AM --> MA_IU
    MA_IU -->|update inode| ITBL
    MA_IU --> MA_DE
    MA_DE -->|update dir entry| DR
    MA_DE --> MA_DW
    MA_DW -->|write file data| DR
    MA_DW -->|reads source files| Base
    MA_DW --> MA_CU
    MA_CU -->|update checksum| SB
    MA_CU -->|update checksum| IBM
    MA_CU --> MA_CU
    MA_CU -->|write updated image| IMG

    %% Click Events
    click MB "https://github.com/waseque199/minivsfs-image-generator-using-c/blob/main/mkfs_builder.c"
    click MA "https://github.com/waseque199/minivsfs-image-generator-using-c/blob/main/mkfs_adder.c"
    click Base "https://github.com/waseque199/minivsfs-image-generator-using-c/tree/main/Base Files/"
    click README "https://github.com/waseque199/minivsfs-image-generator-using-c/blob/main/README.md"

    %% Styles
    classDef exe fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef internal fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef ondisk fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef user fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef docs fill:#FFE4E1,stroke:#333,stroke-width:1px
    classDef files fill:#FFE4E1,stroke:#333,stroke-width:1px
```
