Add structured project documentation

docs/backends.md

@@ -0,0 +1,154 @@
+# Backends
+
+This page summarizes the built-in filesystem implementations in VirtualFS.
+
+## `PhysicalFileSystem`
+
+Backs a virtual subtree with a real local directory.
+
+Characteristics:
+
+- writable
+- creates the root directory if it does not exist
+- maps virtual `/` separators to host-native separators internally
+- supports native file and directory metadata
+
+Good fit for:
+
+- local content directories
+- writable application storage
+- test fixtures backed by temporary directories
+
+## `MemoryFileSystem`
+
+Stores entries entirely in memory.
+
+Characteristics:
+
+- writable
+- no physical path
+- lightweight and fast for temporary content
+
+Good fit for:
+
+- generated content
+- overlays
+- temporary runtime state
+- tests
+
+## `ZipReadFileSystem`
+
+Exposes a ZIP archive as a read-only virtual filesystem.
+
+Characteristics:
+
+- read-only
+- backed by `SharpZipLib`
+- requires a seekable stream
+- optional path scoping to a ZIP subdirectory
+- optional regex filtering
+
+Good fit for:
+
+- packaged assets
+- static content bundles
+- immutable deployment artifacts
+
+## `EmbeddedResourceFileSystem`
+
+Exposes assembly embedded resources as a read-only filesystem.
+
+Characteristics:
+
+- read-only
+- backed by manifest resources
+- optional root namespace trimming
+- optional regex filtering
+
+Good fit for:
+
+- embedded templates
+- application assets bundled in assemblies
+- shipping immutable defaults inside an executable or library
+
+## `FtpFileSystem`
+
+FTP-backed implementation using `FluentFTP`.
+
+Characteristics:
+
+- writable
+- supports file, directory, and symlink listings
+- supports recursive directory deletion
+- opens a fresh FTP connection per operation
+
+Good fit for:
+
+- remote FTP stores where a fuller client implementation is needed
+
+Notes:
+
+- network operations are naturally slower than local backends
+- deep copy/move operations may become expensive
+
+## `SimpleFtpFileSystem`
+
+Minimal FTP implementation based on `FtpWebRequest`.
+
+Characteristics:
+
+- writable
+- simpler than `FtpFileSystem`
+- recursive delete is implemented in library code
+
+Good fit for:
+
+- compatibility scenarios
+- cases where the simpler implementation is sufficient
+
+## `SimpleFtpCachedFileSystem`
+
+Caching layer on top of `SimpleFtpFileSystem`.
+
+Characteristics:
+
+- caches directory listings by path
+- updates cache on some mutations
+- reduces repeated directory enumeration cost
+
+Good fit for:
+
+- FTP trees with repeated read-heavy directory access
+
+## `SFtpFileSystem`
+
+SFTP-backed implementation using `SSH.NET`.
+
+Characteristics:
+
+- writable
+- supports password authentication
+- supports private key authentication
+- can validate host fingerprint
+- can forward exceptions to a callback
+
+Good fit for:
+
+- secure remote filesystem access over SFTP
+
+## Backend Selection Guidance
+
+Choose a backend based on the shape of the content:
+
+- use `PhysicalFileSystem` for local writable data
+- use `MemoryFileSystem` for generated or ephemeral data
+- use `ZipReadFileSystem` for immutable packaged assets
+- use `EmbeddedResourceFileSystem` for assembly-bundled assets
+- use `FtpFileSystem` or `SFtpFileSystem` for remote stores
+- use `SimpleFtpCachedFileSystem` when FTP directory reads are repetitive
+
+Common combinations:
+
+- ZIP as a low-priority base layer + physical overrides as high priority
+- physical content + memory-generated overlay
+- embedded resources + memory patch layer