Design Principles

graph TD
    subgraph CLI
        A[CLI Interface] --> B[Command Parser]
        B --> C{Commands}
        C -->|Bind| D[Bind Command]
        C -->|Mount| E[Mount Command]
        C -->|Session| F[Session Management]
    end

    subgraph Session Management
        G[Session Manager] --> H[Session State]
        G --> I[Named Pipes]
        H --> J[Session Info Files]
        G --> K[Process Management]
    end

    subgraph Filesystem Operations
        L[Filesystem Manager] --> M[9P Protocol]
        L --> N[Mount Operations]
        L --> O[Bind Operations]
    end

    D --> G
    E --> G
    F --> G
    I --> L
    K --> L

    subgraph Storage
        P[/tmp/froggr/sessions/]
        J --> P
        I --> P
    end

Froggr is built on several key design principles that guide its development and usage:

1. Plan 9 Inspiration

Froggr draws heavy inspiration from Plan 9's filesystem architecture, particularly its approach to namespace management. Like Plan 9, Froggr treats everything as a file and uses filesystem operations to manage system resources.

2. Per-Process Namespaces

Each Froggr session maintains its own filesystem namespace, similar to Plan 9's per-process namespaces. This isolation allows for:

• Independent namespace modifications
• Process-specific views of the filesystem
• Clean separation between different applications or services

3. Union Directories

Following Plan 9's union mount concept, Froggr allows multiple directories to be combined into a single view. This enables:

• Layered filesystem composition
• Dynamic content aggregation
• Flexible resource organization

4. Bind Operations

Bind operations are fundamental to Froggr's namespace manipulation:

• Replace: Complete replacement of target content
• Before: Prepend content to existing view
• After: Append content to existing view
• Create: Create new bindings for non-existent paths

5. Server-Based Architecture

Froggr implements a 9P filesystem server that:

• Handles client requests
• Manages namespace operations
• Provides filesystem access
• Maintains session state

6. State Management

Each session's state is:

• Persisted in /tmp/proc/
• Tracked independently
• Cleaned up automatically
• Recoverable after crashes

7. Clean Separation of Concerns

The system is designed with clear separation between:

• Filesystem operations
• Namespace management
• Session handling
• State persistence
• Client interactions

8. Explicit Over Implicit

Froggr favors explicit operations:

• Clear bind modes
• Visible namespace changes
• Traceable state modifications
• Documented side effects

9. Fail-Safe Operations

Operations are designed to:

• Validate inputs
• Check permissions
• Handle errors gracefully
• Clean up on failure
• Maintain consistency

10. Unix Integration

While inspired by Plan 9, Froggr integrates well with Unix systems:

• Works with existing filesystems
• Respects Unix permissions
• Uses familiar path conventions
• Provides Unix-like tools