# guille-ux/headerfs architecture

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

- Interactive diagram: https://gitdiagram.com/guille-ux/headerfs
- Repository: https://github.com/guille-ux/headerfs

## Overview

##### Project type and purpose
- This is a C-based filesystem module (“HeaderFs”) intended to be part of an operating system kernel. It provides a minimal, header-based filesystem interface plus a corresponding ANSI C driver for disk I/O.
- It’s not a full-stack application or microservice. Rather it’s a systems-level library/driver component meant to plug into a larger OS kernel’s VFS layer.

##### File structure
- Top-level:
- fs.h         – Public filesystem API header.
- LICENSE, README.md
- drivers/ansi-c:
- fs.c, fs.h   – Filesystem implementation.
- disk.c, disk.h – Raw disk I/O driver in ANSI C.
- libs:
- disk.h       – Shared disk interface definitions.
- io.h         – Generic I/O abstractions (block reads/writes).
- Pattern: a two-layer architecture
- Core FS layer (fs.c/.h)
- Underlying disk driver layer (disk.c/.h)
- Common I/O abstractions in libs

##### Key README insights
- “Header based FileSystem”: small, simple FS.
- Not compatible with ext4/FAT; purely in-kernel.
- Planned future compatibility layers.

##### Detailed separation of components
- Internal division of HeaderFs:
- Metadata management (superblock, inodes)
- Data block allocation
- How the I/O abstraction library could be swapped out or extended.
- Where new filesystem compatibility layers would hook in (future ext4/FAT adapters).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kernel Components
    VFS["VFS Consumer"]:::apiLib
    HeaderAPI["HeaderFs Public API (fs.h)"]:::apiLib
    subgraph "HeaderFs Core"
        FS_C["fs.c"]:::apiLib
        FS_H["fs.h"]:::apiLib
        CoreMeta["Metadata Management"]:::apiLib
        CoreAlloc["Data Block Allocation"]:::apiLib
    end
    IoAbstraction["I/O Abstraction (libs/io.h)"]:::apiLib
    DiskDefs["Disk Interface Definitions (libs/disk.h)"]:::apiLib
    subgraph "ANSI-C Disk Driver"
        DiskC["disk.c"]:::driver
        DiskH["disk.h"]:::driver
    end
    BlockDev["Block Device"]:::hardware
    FutureExt["Future FS Adapters"]:::driver

    %% Connections
    VFS -->|"fs_open(), fs_read()"| HeaderAPI
    HeaderAPI -->|"HeaderFs calls"| FS_C
    FS_C -->|manages| CoreMeta
    FS_C -->|allocates| CoreAlloc
    CoreMeta -->|"read_block(), write_block()"| IoAbstraction
    CoreAlloc -->|"read_block(), write_block()"| IoAbstraction
    IoAbstraction -->|"uses interface"| DiskDefs
    DiskDefs -->|"implements interface"| DiskC
    DiskC -->|"raw I/O"| BlockDev
    FutureExt -->|"could hook here"| DiskDefs

    %% Click Events
    click HeaderAPI "https://github.com/guille-ux/headerfs/blob/main/fs.h"
    click FS_C "https://github.com/guille-ux/headerfs/blob/main/drivers/ansi-c/fs.c"
    click FS_H "https://github.com/guille-ux/headerfs/blob/main/drivers/ansi-c/fs.h"
    click IoAbstraction "https://github.com/guille-ux/headerfs/blob/main/libs/io.h"
    click DiskDefs "https://github.com/guille-ux/headerfs/blob/main/libs/disk.h"
    click DiskC "https://github.com/guille-ux/headerfs/blob/main/drivers/ansi-c/disk.c"
    click DiskH "https://github.com/guille-ux/headerfs/blob/main/drivers/ansi-c/disk.h"

    %% Styles
    classDef apiLib fill:#E8F4FD,stroke:#0366D6
    classDef driver fill:#FFF5E1,stroke:#C07100
    classDef hardware fill:#E1F7E7,stroke:#00875A
```
