DOCS

docs/architecture/filesystem.md

@@ -0,0 +1,28 @@
+# Filesystem Architecture
+
+BoredOS implements a rudimentary but functional filesystem layer designed to support reading system assets and user applications during runtime.
+
+## Virtual File System (VFS)
+
+The Virtual File System acts as an abstraction layer across different underlying storage mechanisms (even if, currently, only one type is fully utilized). System calls targeting files (`SYS_FS`) route through the VFS rather than interacting with the disk directly.
+
+Key VFS functionalities include:
+-   **File Descriptors**: Mapping integer IDs to internal file structures for userland processes.
+-   **Standard Operations**: Standardizing `open()`, `read()`, `write()`, `close()`, `seek()`, and directory listings.
+-   **Path Parsing**: Resolving absolute and relative paths.
+
+## FAT32 Implementation
+
+The primary filesystem logic in `fat32.c` has a dual nature, supporting both an in-memory RAM filesystem for booting and standard block devices for external storage.
+
+### Booting and the RAMFS
+Since BoredOS boots from a CD-ROM ISO image generated by `xorriso`, it does not read directly off the CD to execute applications.
+1.  **ISO Booting**: During boot, Limine loads necessary files (such as userland `.elf` binaries, fonts, and wallpapers) into memory as standard boot modules.
+2.  **RAM Simulation**: The FAT32 filesystem code parses these loaded memory modules and automatically constructs a synthetic FAT32 directory tree inside RAM.
+3.  **Root Filesystem**: All active execution of built-in GUI and CLI apps occurs off this read-only, in-memory FAT32 simulation.
+
+### ATA Disk Support
+Beyond the core RAMFS used for booting, the FAT32 implementation natively supports interacting with permanent storage:
+1.  **ATA Block Driver**: The kernel features an ATA block device driver capable of communicating with physical hard disks (or raw disk images attached via QEMU).
+2.  **Partition Compatibility**: The driver can recognize and natively mount external ATA disks formatted as single FAT32 filesystems or structured with a Master Boot Record (MBR) partition table.
+3.  **VFS Integration**: When external storage is mounted, the VFS delegates operations down directly to the FAT32 driver, which will read native sectors across the ATA interface.