commit 0040ae531c3a09ac23c9a7f2677458c6b022b98e
Author: Ultradesu <ultradesu@hexor.cy>
Date:   Tue Mar 10 14:09:01 2026 +0000

    init

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..5eeb89c
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,87 @@
+# Furumi-ng: Distributed Virtual File System
+
+## Project Overview
+This document describes the architectural vision and technical requirements for a modern, high-performance distributed virtual file system built in Rust. The system allows a remote client to connect to a server with authorization, list directories recursively, and mount the remote directory as a local virtual file system. It is designed as a faster, more reliable, and modern alternative to WebDAV.
+
+## Core Requirements
+1. **Cross-Platform Support:** Initial support for Linux and macOS. The backend server and client mounting logic must be logically separated so that new OS support (e.g., Windows) can be added solely by writing a new mount layer without altering the core backend or client networking code.
+2. **Read-Only First:** The initial implementation will support read-only operations, with an architecture designed to easily accommodate write operations in subsequent phases.
+3. **Memory Safety & Reliability:** The entire stack (server, shared client core, and mount layers) will be implemented in **Rust** to leverage its strict compiler guarantees, memory safety, and high-performance asynchronous ecosystem.
+
+## High-Level Architecture
+
+The architecture is divided into three main components: Server, Shared Client Core, and OS-Specific Mount Layers.
+
+### 1. Transport & Protocol (gRPC)
+- **Protocol:** gRPC over HTTP/2.
+- **Why gRPC:** Provides strong typing via Protobuf, multiplexing, and robust streaming capabilities which are essential for transferring large file chunks efficiently.
+- **Security:** Requires TLS (e.g., mTLS or JWT via metadata headers) to secure data in transit.
+
+### 2. Server (Linux Backend)
+The server role is to expose local directories to authorized clients safely and asynchronously.
+- **Runtime:** `tokio` for non-blocking I/O.
+- **Security Validation:** Strict path sanitization (protection against Path Traversal). The server restricts clients strictly to their allowed document root.
+- **VFS Abstraction:** Backend logic will be abstracted behind a Rust trait. This allows future swapping of the storage backend (e.g., Local Disk -> AWS S3, or In-Memory for testing) without changing the gRPC transport layer.
+
+### 3. Client Architecture
+To maximize code reuse and maintainability, the client is split into two layers:
+
+#### A. Shared Client Core (Cross-Platform)
+A Rust library containing all OS-agnostic logic:
+- **Network Client:** Handles gRPC connections, request retries, backoff strategies, and error handling.
+- **VFS Cache:** An in-memory cache for metadata (TTL-based) to dramatically reduce network latency for high-frequency `stat` / `getattr` calls generated by file managers or terminals.
+- **VFS Translator:** Maps VFS operations into remote gRPC RPC calls.
+
+#### B. OS-Specific Mount Layer
+Thin executable wrappers that consume the Shared Client Core and handle OS integration:
+- **Linux:** Uses the `fuser` crate (binds to `libfuse`) to mount and handle events from `/dev/fuse`.
+- **macOS:** Can utilize `macFUSE` via the `fuser` crate initially. Future iterations may explore native Apple `FileProvider` frameworks using FFI to bypass third-party kext requirements.
+- **Windows (Future):** Will wrap libraries like `WinFSP` or `dokany` to integrate with the Windows internal VFS.
+
+## API Design (Read-Only Foundation)
+The initial Protobuf specification will involve core remote procedure calls (RPCs) to support read-only mode:
+
+```protobuf
+syntax = "proto3";
+package virtualfs;
+
+message PathRequest {
+  string path = 1;
+}
+
+message AttrResponse {
+  uint64 size = 1;
+  uint32 mode = 2; // Permissions and file type
+  uint64 mtime = 3; // Modification time
+  // ... other standard stat attributes
+}
+
+message DirEntry {
+  string name = 1;
+  uint32 type = 2; // File or Directory
+}
+
+message ReadRequest {
+  string path = 1;
+  uint64 offset = 2;
+  uint32 size = 3;
+}
+
+message FileChunk {
+  bytes data = 1;
+}
+
+service RemoteFileSystem {
+  // Get file or directory attributes (size, permissions, timestamps). Maps to stat/getattr.
+  rpc GetAttr (PathRequest) returns (AttrResponse);
+  
+  // List directory contents. Uses Server Streaming to handle massively large directories efficiently.
+  rpc ReadDir (PathRequest) returns (stream DirEntry);
+  
+  // Read chunks of a file. Uses Server Streaming for efficient chunk delivery based on offset/size.
+  rpc ReadFile (ReadRequest) returns (stream FileChunk);
+}
+```
+
+## Future Expansion: Write Operations
+The design ensures seamless expansion to a read-write file system. Future RPCs such as `CreateFile`, `MkDir`, `Remove`, `Rename`, and `WriteChunk` (utilizing Client Streaming or Bi-directional Streaming in gRPC) can be added without restructuring the foundational architecture.