# subhamx/gmailstorejfs architecture

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

- Interactive diagram: https://gitdiagram.com/subhamx/gmailstorejfs
- Repository: https://github.com/subhamx/gmailstorejfs

## Overview

##### Project Type & Purpose
- GmailStorejFS is a FUSE-based filesystem written in C that mounts a Gmail mailbox locally. It acts as a bridge between the user’s filesystem and Gmail’s IMAP interface.
- It synchronizes between local operations and remote mailbox updates while applying features like caching, quoted-printable parsing, and special file/label handling (e.g., append-only permissions on certain files).

##### File Structure
- The top-level “src” directory contains the main application (main.c) that starts the FUSE filesystem.
- The “src/services” directory holds numerous header files representing discrete service functions for different IMAP/email operations (e.g., fetching emails, managing labels, deleting emails, etc.). These represent the core operations that map traditional filesystem operations (like read, write, mkdir, unlink) to corresponding Gmail actions.
- The “src/utils” directory contains support functions (custom string manipulation, decoding, hashmap, UUID operations) that help in processing data and managing identifiers.

##### Main Components
- FUSE Interface Layer: This is the entry point (main.c) which initializes and mounts the filesystem; include the integration with the libfuse library.
- Email Service Handlers: Represent the set of modular service components (e.g., add_label_to_email, create_new_mail, delete_email, fetch_email_content) that are responsible for sending/receiving data via IMAP using libcurl.
- Synchronization & Caching: Illustrate the caching component that optimizes performance by instantly reflecting both local and remote changes.
- External Libraries & Dependencies: Clearly mark libfuse (for filesystem operations), libcurl (for network interactions with Gmail via IMAP), and uuid (for unique identification of emails and possibly files).

##### Relationships & Interactions
- Start at the Application Entry Point (main.c), which sets up the FUSE mount and registers various callbacks.
- Each callback (e.g., readdir, read, write, mkdir) will then delegate to corresponding service functions in the “src/services” modules.
- Email service components will further communicate with Gmail servers over IMAP – these interactions are managed by libcurl calls within these services.
- Utility modules are used by both the service functions and FUSE operations to manage common data transformations and ensure consistency (e.g., decoding email contents, managing hashmap caches, string operations).
- The data flow is bidirectional. Changes on the local filesystem are immediately synced to Gmail (local write → service function → libcurl/IMAP), and updates on the mailbox reflect back on the local cache (external update → caching module → FUSE data retrieval).

##### Architectural Patterns & Design Principles
- Modularity: Separate responsibility among the FUSE initialization, service modules for interacting with Gmail, and utility modules.
- Caching and Performance: Highlight the intelligent caching system that optimizes throughput and reduces direct network overhead.
- Security & Permissions: Note the permission model (e.g., “append-only” on special files) integrated into the logic, which is enforced through service calls.

##### Final Recommendations
- A secondary block or callout that represents the caching and utility functions, showing how they assist with data transformations and performance.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Initiator
    USER("User/Host System"):::external

    %% FUSE Interface Layer
    subgraph "FUSE Interface Layer"
        FUSE("FUSE Interface (main.c)"):::core
    end

    %% Email Services
    subgraph "Email Services"
        EMAIL("Email Service Handlers"):::core
    end

    %% Utility Functions
    subgraph "Utility Functions"
        UTILS("Utility Libraries"):::utils
    end

    %% Caching & Synchronization
    subgraph "Caching & Synchronization"
        CACHE("Caching Module"):::cache
    end

    %% External Interfaces & Dependencies
    subgraph "External Interfaces"
        GMAIL("Gmail IMAP Server"):::external
        LIBFUSE("libfuse"):::external
        LIBCURL("libcurl"):::external
        UUID("uuid"):::external
    end

    %% Testing Components (Production validation)
    subgraph "Testing"
        TEST("Test Suite"):::test
    end

    %% Relationships
    USER -->|"initiates"| FUSE
    FUSE -->|"registers_callbacks"| EMAIL
    FUSE -->|"calls_utilities"| UTILS
    FUSE ---|"depends_on"| LIBFUSE
    EMAIL -->|"performs_IMAP_via"| LIBCURL
    EMAIL -->|"accesses"| GMAIL
    EMAIL -->|"uses"| UTILS
    EMAIL ---|"requires"| UUID
    FUSE -->|"local_update"| CACHE
    CACHE -->|"syncs_with"| FUSE
    EMAIL -->|"remote_update"| CACHE
    CACHE -->|"updates"| EMAIL
    TEST -.->|"validates"| FUSE
    TEST -.->|"validates"| EMAIL

    %% Click Events
    click FUSE "https://github.com/subhamx/gmailstorejfs/blob/main/src/main.c"
    click EMAIL "https://github.com/subhamx/gmailstorejfs/tree/main/src/services"
    click UTILS "https://github.com/subhamx/gmailstorejfs/tree/main/src/utils"
    click TEST "https://github.com/subhamx/gmailstorejfs/tree/main/src/test"

    %% Styles
    classDef core fill:#9fdfbf,stroke:#333,stroke-width:2px;
    classDef utils fill:#9fdfff,stroke:#333,stroke-width:2px;
    classDef cache fill:#ffedbd,stroke:#333,stroke-width:2px;
    classDef external fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef test fill:#b0bec5,stroke:#333,stroke-width:2px;
```
