diff --git a/README.md b/README.md
index 04798b9..6d3ef09 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,84 @@ int main() {
 
 <a name="module-vfs"></a>
 ### 4. VFS
-(Documentation pending implementation)
+The VFS (Virtual File System) module provides a unified interface for file operations by mapping virtual paths to user defined providers. 
+
+#### Implementing a file provider
+To create a new storage backend (e.g., a zip loader, encrypted volume, etc), you must inherit from `IFileProvider`.
+```cpp
+#include <seallib/vfs.h>
+
+using namespace seallib;
+
+class MyCustomProvider : public IFileProvider {
+public:
+    // checks if file exists
+    bool exists(const std::string& path) const override {
+        /*
+            implementation logic here
+        */
+        return true; 
+    }
+
+    // loads data from provider to outBuffer
+    VFSResult readFile(const std::string& path, FileBuffer& outBuffer) const override {
+        /* 
+           1. locate the file in your system.
+           2. if not found, return VFSResult::FileNotFound.
+           3. allocate memory: outBuffer.data = std::make_unique<uint8_t[]>(size);
+           4. copy data into outBuffer.data and set outBuffer.size = size;
+        */
+        return VFSResult::Success;
+    }
+
+    // write data from a buffer to your provider
+    VFSResult writeFile(const std::string& path, const FileBuffer& buffer) override {
+        /* 
+           VFS ensures 'buffer' is valid (data != nullptr) before calling this.
+           return VFSResult::AccessDenied if your provider is read-only or if that path shouldn't be written to
+        */
+        return VFSResult::Success;
+    }
+
+    // generic file management operations
+    VFSResult deleteFile(const std::string& path) override { return VFSResult::Success; }
+    VFSResult createDirectory(const std::string& path) override { return VFSResult::Success; }
+
+    // list all files and subdirectories within a given path
+    std::vector<std::string> listDirectory(const std::string& path) const override {
+        // note: directories should ideally end with a '/' for clarity
+        return { "file1", "file2", "file3" };
+    }
+
+    // optional: return a name for debugging/logging
+    std::string getProviderName() const override { return "MyCustomProvider"; }
+};
+```
+
+#### Example usage
+```c++
+#include <seallib/vfs.h>
+
+using namespace seallib;
+
+int main() {
+    VirtualFileSystem vfs;
+
+    /*
+        mount a disk provider to the virtual "assets" folder
+        higher priority (10 in this case) means this mount is checked before others
+    */
+    vfs.mount("/assets", std::make_unique<DiskFileProvider>("./data"), 10);
+
+    // reading a file (Paths are automatically normalized to remove '../' etc.)
+    FileBuffer buffer;
+    if (vfs.readFile("/assets/somefile.bin", buffer) == VFSResult::Success) {
+        std::string rawData = buffer.toString();
+    }
+
+    return 0;
+}
+```
 
 ---