# kartikx/distributed-file-system architecture

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

- Interactive diagram: https://gitdiagram.com/kartikx/distributed-file-system
- Repository: https://github.com/kartikx/distributed-file-system

## Overview

##### Project type and purpose
- From the file tree and code names (main.go, server.go, client.go, introducer.go, ring.go, piggyback.go, membershipInfo.go, messages.go, caching.go, file.go), this is a Go-based distributed systems project implementing a membership/gossip protocol and file‐service API across a cluster. The “introducer” suggests a bootstrap node, “ring” indicates a logical overlay, and “piggyback” implies gossip piggybacking.

##### File structure
- Top-level Go sources:
- main.go – application entry point
- server.go / client.go – RPC or REST stubs for service and client operations
- introducer.go – cluster join coordinator
- ring.go – ring overlay management
- piggyback.go / messages.go / membershipInfo.go – gossip protocol and membership state
- caching.go / file.go – file‐service logic and caching layer
- utils.go / constants.go / logger.go – shared utilities, configuration, and logging
- demo/ and bash_scripts/ – setup and demo scripts (not part of runtime).
- go.mod/go.sum – module and dependencies.

##### Key README insights
- The README is the default GitLab template and does not describe architecture. We infer architecture purely from code.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Client["External Client"]:::external
    IntroducerNode["Introducer"]:::external
    DemoScripts["Demo & Setup Scripts"]:::external
    BashScripts["bash_scripts/"]:::external

    %% Network Transport
    Network["Network Transport\n(UDP/TCP)"]:::network

    %% Server Node Subgraph
    subgraph "Server Node"
        direction TB
        Main["Application Entry Point\n(main.go)"]:::module
        APIServer["API Layer (Server)\n(server.go)"]:::module
        APIClient["API Layer (Client)\n(client.go)"]:::module
        subgraph "Membership Subsystem"
            direction TB
            RingManager["Ring Manager\n(ring.go)"]:::module
            PiggybackEngine["Piggyback Engine\n(piggyback.go)"]:::module
            Messages["Message Types\n(messages.go)"]:::module
            MembershipInfo["Membership Info\n(membershipInfo.go)"]:::module
            IntroducerModule["Introducer Module\n(introducer.go)"]:::module
        end
        subgraph "File & Cache"
            direction TB
            FileService["File Service\n(file.go)"]:::module
            Caching["Caching Layer\n(caching.go)"]:::module
        end
        subgraph "Utilities & Logging"
            direction TB
            Utils["Utilities\n(utils.go)"]:::module
            Constants["Config Constants\n(constants.go)"]:::module
            Logger["Logging\n(logger.go)"]:::module
        end
    end

    %% Flows
    Client -->|"Read/Write RPC"| APIServer
    APIServer -->|"Invoke FileService"| FileService
    APIServer -->|"Invoke Caching"| Caching

    Main --> APIServer
    Main --> APIClient
    Main --> RingManager
    Main --> FileService
    Main --> Utils

    %% Join Flow
    APIClient -->|"Join Request"| IntroducerNode
    IntroducerNode -.->|"Initial Membership List"| APIClient
    APIClient -.->|"Bootstrap to Ring Manager"| RingManager

    %% Gossip Flow
    RingManager -.->|"Heartbeat Timer"| PiggybackEngine
    PiggybackEngine -->|"GossipMsg"| Network
    Network -->|"GossipMsg"| PiggybackEngine
    PiggybackEngine --> MembershipInfo
    MembershipInfo --> RingManager

    %% Client-to-Introducer on startup
    Client -.->|"JoinRequest"| IntroducerNode

    %% Demo & Setup Scripts reference
    DemoScripts -.-> Main
    BashScripts -.-> Main

    %% Click Events
    click Client "https://github.com/kartikx/distributed-file-system/tree/main/n/a"
    click APIServer "https://github.com/kartikx/distributed-file-system/blob/main/server.go"
    click APIClient "https://github.com/kartikx/distributed-file-system/blob/main/client.go"
    click IntroducerModule "https://github.com/kartikx/distributed-file-system/blob/main/introducer.go"
    click RingManager "https://github.com/kartikx/distributed-file-system/blob/main/ring.go"
    click PiggybackEngine "https://github.com/kartikx/distributed-file-system/blob/main/piggyback.go"
    click Messages "https://github.com/kartikx/distributed-file-system/blob/main/messages.go"
    click MembershipInfo "https://github.com/kartikx/distributed-file-system/blob/main/membershipInfo.go"
    click FileService "https://github.com/kartikx/distributed-file-system/blob/main/file.go"
    click Caching "https://github.com/kartikx/distributed-file-system/blob/main/caching.go"
    click Utils "https://github.com/kartikx/distributed-file-system/blob/main/utils.go"
    click Constants "https://github.com/kartikx/distributed-file-system/blob/main/constants.go"
    click Logger "https://github.com/kartikx/distributed-file-system/blob/main/logger.go"
    click Main "https://github.com/kartikx/distributed-file-system/blob/main/main.go"
    click BashScripts "https://github.com/kartikx/distributed-file-system/tree/main/bash_scripts/"
    click DemoScripts "https://github.com/kartikx/distributed-file-system/tree/main/demo/"

    %% Styles
    classDef external fill:#acf,stroke:#069,stroke-width:2px
    classDef module fill:#bbf,stroke:#036,stroke-width:1px
    classDef network fill:#fca,stroke:#963,stroke-width:2px,stroke-dasharray: 5 5
```
