# goelk2004/virtual-file-system-engine architecture

> Architecture diagram of the GitHub repository goelk2004/virtual-file-system-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/goelk2004/virtual-file-system-engine
- Repository: https://github.com/goelk2004/virtual-file-system-engine

## Overview

##### Project type and purpose
- This is a systems‐level C++ project implementing a Virtual File System (VFS) from scratch. It simulates a real-world disk‐based file system (ext4/NTFS-like) with features such as journaling, permission management, metadata caching, multi‐filesystem mounting, crash recovery, and a command-line interface.

##### File structure
- Top-level files:
- Makefile – build script
- README.md – project overview
- LICENSE – copyright
- Directories:
- / – all public header files (interfaces for CLI, VFS, journaling, mount manager, metadata manager, etc.)
- src/ – implementation of each component; main.cpp is the entry point
- journal/ – runtime journal log file (write‐ahead logging)

##### README for extra insights
- Core subsystems called out: metadata (B+ tree), allocation (bitmap + extents), journaling, caching, mount management, multithreading, permission/user management.
- CLI commands define the external “UI” layer that invokes VFS operations.

##### Main components
a. Frontend/Presentation
- CLI Module (CLI.cpp/CLI.h, cliFunctions)
b. VFS Interface Layer
- VirtualFileSystem (VFS.cpp/VFS.h) – exposes create, read, write, mount, unmount, etc.
c. Core Services
- MetadataManager (metaDataManager.h/cpp; centralised metadata table, B+ Tree)
- AllocationManager (bitmap + extents; disk.cpp)
- JournalingSubsystem (journaling.h/cpp; write-ahead log in journal.log)
- RollbackManager (rollback.h/cpp; crash rollback logic)
- MountManager (mountManager.h/cpp; multi‐filesystem mounting)
- PermissionManager/UserManager (system.h, user/group related code)
- CacheManager (in-memory cache for superblock, metadata, bitmap)
- MultithreadingController (multithreading.h/cpp)
d. Data Layer
- Disk I/O Interface (disk.cpp/disk.h) – raw block reads/writes from myDisk.img
- Journal File (journal/journal.log)

##### Relationships and interactions
- CLI → Calls VFS interface (synchronous).
- VFS → invokes Core Services in layered order:
- PermissionManager → check ACLs
- MetadataManager → query/update file metadata
- AllocationManager → allocate/free blocks
- CacheManager → check/invalidate caches
- JournalingSubsystem → record operation in journal
- Disk I/O → commit blocks to myDisk.img
- RollbackManager → if crash/error, replay journal on startup
- MountManager handles routing of VFS calls to the correct disk instance.
- MultithreadingController synchronizes concurrent CLI operations.

##### Architectural patterns and design principles
- Layered architecture (Presentation → Interface → Services → Data)
- Single Responsibility per module (e.g., journaling only handles logs, allocation only handles blocks)
- Modular, pluggable components (e.g., you could swap B+ Tree for another index)
- Write‐Ahead Logging for fault tolerance
- In‐memory caching for performance

##### Relevant technologies/frameworks
- C++17 with custom classes and header/source separation
- Makefile for build orchestration
- Raw disk image file (myDisk.img) and journal.log for persistence

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        CLI["CLI Module"]:::presentation
    end

    subgraph "Interface Layer"
        VFS["VirtualFileSystem (VFS)"]:::interface
    end

    subgraph "Core Services"
        subgraph "File System Engine"
            Centralised["Centralised Metadata Routing"]:::core
            FileOps["File Features"]:::core
            DirMgr["Directory Management"]:::core
            FSAbstr["Filesystem Abstraction"]:::core
            Structs["Data Structures & Hash"]:::core
        end
        Metadata["MetadataManager"]:::core
        Allocation["AllocationManager"]:::core
        Journaling["JournalingSubsystem"]:::core
        Rollback["RollbackManager"]:::core
        Mount["MountManager"]:::core
        Permission["PermissionManager/UserManager"]:::core
        Cache["CacheManager"]:::core
        Threading["MultithreadingController"]:::core
    end

    subgraph "Data Layer"
        DiskIO["Disk I/O Interface"]:::data
        JournalFile["Journal File"]:::data
        DiskImg["Disk Image: myDisk.img"]:::data
    end

    %% Connections
    CLI -->|invokes| VFS
    VFS -->|route via mount| Mount
    VFS -->|check| Permission
    VFS -->|interface to engine| Centralised
    Centralised -->|metadata ops| Metadata
    Centralised -->|allocation ops| Allocation
    Metadata -->|uses cache| Cache
    Allocation -->|writes| Journaling
    Journaling -->|log to| JournalFile
    Journaling -->|commit| DiskIO
    DiskIO -->|store blocks| DiskImg
    Rollback -->|replay on startup| JournalFile
    Rollback -->|restore| DiskImg
    Mount -->|mount fs| DiskIO
    VFS -->|sync threads| Threading
    VFS -->|file features| FileOps
    FileOps --> DirMgr
    DirMgr --> Structs
    FSAbstr --> Metadata

    %% Click Events
    click CLI "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/CLI.h"
    click VFS "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/VFS.h"
    click Metadata "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/metaDataManager.h"
    click Allocation "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/disk.h"
    click Journaling "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/journaling.h"
    click Rollback "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/rollback.h"
    click Mount "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/mountManager.h"
    click Permission "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/system.h"
    click Cache "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/helpers.h"
    click Threading "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/multithreading.h"
    click FileOps "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/fileFeatures.h"
    click DirMgr "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/directory.h"
    click Centralised "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/centralised.h"
    click FSAbstr "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/filesystem.h"
    click Structs "https://github.com/goelk2004/virtual-file-system-engine/blob/main/include/structs.h"
    click DiskIO "https://github.com/goelk2004/virtual-file-system-engine/blob/main/src/disk.cpp"
    click JournalFile "https://github.com/goelk2004/virtual-file-system-engine/blob/main/journal/journal.log"

    %% Styles
    classDef presentation fill:#D0E6FF,stroke:#333,stroke-width:1px;
    classDef interface fill:#CFFFE5,stroke:#333,stroke-width:1px;
    classDef core fill:#DFFFD0,stroke:#333,stroke-width:1px;
    classDef data fill:#EEEEEE,stroke:#333,stroke-width:1px;
```
