# vaelatern/shellfs architecture

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

- Interactive diagram: https://gitdiagram.com/vaelatern/shellfs
- Repository: https://github.com/vaelatern/shellfs

## Overview

##### Main Components

a) Core Components:
- FUSE Interface Layer
- Command Execution Engine
- Virtual File System Manager
- File Operation Handlers
- Passthrough System

b) Key Interactions:
- User Space <-> Kernel Space communication
- Command Execution Flow
- File System Operations Flow

**Top Layer: User Applications**

**Middle Layer: ShellFS Components**

**Bottom Layer: Operating System**

##### Specific Component Details

a) User Space Layer:
- Standard file operations (read/write)

b) ShellFS Core (Middle Layer):
- FUSE Bridge Component
- Handles mounting and file system operations
- Interfaces with the kernel's VFS
- Command Executor
- Manages command execution
- Captures command output
- Virtual File System Manager
- Handles virtual file representation
- Manages special files (marked with #command#)
- File Operations Handler
- Implements read/write operations
- Manages file attributes

c) Operating System Layer:
- FUSE Kernel Module
- Native File System
- Process Management

##### Implementation Details to Highlight

- FUSE integration points
- Command execution isolation
- File system mounting process
- Regular file passthrough mechanism

##### Notes for Scale

- Enough detail to show the unique aspects of ShellFS
- Maintain clarity in showing how command output becomes file content

##### The FUSE implementation details

This system design should clearly show how ShellFS bridges the gap between command execution and file system representation, making it clear how it achieves its core functionality of presenting command outputs as files.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph User_Space
        UA[User Applications]
        MO["Mount Operations"]
    end

    subgraph ShellFS_Core
        FUSE[FUSE Bridge]
        CMD[Command Executor]
        VFS[Virtual File System Manager]
        FOH[File Operations Handler]
        PT[Passthrough System]
    end

    subgraph OS_Layer
        KM[FUSE Kernel Module]
        NFS[Native File System]
        PM[Process Management]
    end

    subgraph File_Types
        VF["Virtual Files (#command#)"]
        RF[Regular Files]
        DS[Directory Structure]
    end

    %% Connections
    UA --> FUSE
    MO --> FUSE
    FUSE --> VFS
    VFS --> CMD
    VFS --> FOH
    FOH --> PT
    CMD --> PM
    PT --> NFS
    FUSE --> KM

    %% Click events for component mapping
    click FUSE "https://github.com/Vaelatern/shellfs/blob/master/cmd/shellfs/main.go"
    click VF "https://github.com/Vaelatern/shellfs/tree/master/examples/basic-mount-origin/#my-info#"
    click RF "https://github.com/Vaelatern/shellfs/tree/master/examples/basic-mount-origin/a-normal-file"
    click DS "https://github.com/Vaelatern/shellfs/tree/master/examples/basic-mount-origin/a-subdir"
    click MO "https://github.com/Vaelatern/shellfs/blob/master/examples/create-and-mount-fs.sh"

    %% Styling
    classDef userSpace fill:#FFE5CC,stroke:#333,stroke-width:2px
    classDef core fill:#CCE5FF,stroke:#333,stroke-width:2px
    classDef os fill:#E5FFCC,stroke:#333,stroke-width:2px
    classDef files fill:#FFE6FF,stroke:#333,stroke-width:2px

    class UA,MO userSpace
    class FUSE,CMD,VFS,FOH,PT core
    class KM,NFS,PM os
    class VF,RF,DS files

    %% Legend
    subgraph Legend
        L1[User Space Components]:::userSpace
        L2[Core Components]:::core
        L3[OS Components]:::os
        L4[File System Elements]:::files
    end
```
