# gchinar/gp33-distributed-computing-assignment1 architecture

> Architecture diagram of the GitHub repository gchinar/gp33-distributed-computing-assignment1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gchinar/gp33-distributed-computing-assignment1
- Repository: https://github.com/gchinar/gp33-distributed-computing-assignment1

## Overview

##### What this project is (type + purpose)
This is a small **Python distributed systems assignment** consisting of:
- a **CLIENT**
- **SERVER1**
- **SERVER2**
- shared utilities in **common.py**

The README explicitly says it’s about **replica file comparison**, so the architecture is almost certainly:
- a client sends a request involving a file (or filename / checksum / contents)
- one server coordinates or compares against another replica
- the system checks whether replicas match (and possibly returns “match/mismatch” + details)

It also references running “on the cloud node” and a **private IP for SERVER2**, which strongly suggests a **multi-node deployment** where SERVER1 must reach SERVER2 over an internal network.

##### File structure (what to map into components)
Top-level files are the entire system:
- **client.py** → the client process, likely CLI-driven; originates requests.
- **server1.py** → server process #1; likely “primary/coordinator” (since it needs SERVER2’s private IP).
- **server2.py** → server process #2; likely holds a replica and responds to comparisons/requests.
- **common.py** → shared code used by client + servers (very typical for message formats, constants like ports, serialization helpers, checksum routines, socket helpers).
- **.gitignore** → not architecture-relevant.

This is not layered “frontend/backend”; it’s **process-oriented** (three programs) with **network communication** between them.

- “CLIENT, SERVER1 and SERVER2” are first-class actors (three nodes/processes).
- “replica file comparison” is the core function (show data flow: file/copy/checksum/compare).
- “Replace <ACTUAL_SERVER2_PRIVATE_IP> in the SERVER1 start command” implies:
- SERVER1 initiates communication to SERVER2 (outbound dependency).
- SERVER2 is addressable via private network (deployment detail).

##### Client Process (client.py)
- Role: request initiator
- Interfaces: network client (socket/HTTP/RPC—whatever code uses)
- Data it sends: file name / file bytes / checksum / request type

##### Server1 Process (server1.py)
- Role: coordinator/primary endpoint for client
- Inbound interface: listens for Client requests
- Outbound interface: connects to Server2 using configured private IP
- Responsibilities (likely): request handling, orchestration, comparison logic, merging responses

##### Server2 Process (server2.py)
- Role: replica/secondary
- Inbound interface: listens for Server1 requests
- Responsibilities (likely): provide replica state (file bytes/checksum/metadata) for comparison

##### Shared Library (common.py)
- Not a runtime “service,” but architecturally important:
- message schema / constants (ports, hostnames)
- serialization/deserialization
- hashing/checksum utilities
- Component: “uses common.py for protocol + hashing”.

##### Replica Storage (implicit)
Even if not shown as separate files, replica comparison implies each server has some local state:
- “Local File System / Replica Store” attached to Server1
- “Local File System / Replica Store” attached to Server2

You want to show **two communication paths**:

##### Client → Server1 (request/response)
- “CompareRequest(file_id | filename | bytes | checksum)”
- “CompareResponse(match? diff? metadata?)”
- That Server1 is the **public endpoint** from client’s perspective.

##### Server1 ↔ Server2 (replica inquiry + response)
- Because README forces Server1 to know Server2 IP, show Server1 initiating:
- **Server1 → Server2: ReplicaQuery(file_id / checksum request / file fetch)**
- **Server2 → Server1: ReplicaInfo(checksum/bytes/version/mtime)**

##### Server ↔ Local Storage
- **Server1 → Server1 Storage**: read local replica file/checksum
- **Server2 → Server2 Storage**: read local replica file/checksum

##### Architectural patterns/design principles used here
From structure + README, the likely pattern is:
- **Two-tier distributed setup** with a **client** and **two server replicas**
- **Primary/coordinator (Server1)** pattern:
- Client talks to Server1
- Server1 talks to Server2
- **Replica comparison** pattern:
- Compare by checksum/hash first; optionally fetch full content if needed
- **Shared protocol module** (common.py) to avoid drift in message formats

- Server2 is not directly contacted by the client (unless code says otherwise)
- Server1 is responsible for contacting Server2 (explicit dependency via private IP)

##### Relevant technologies (based on what’s visible)
- **Language**: Python
- **IPC/Network**: “network sockets / RPC” (verify by inspecting code; if it’s raw `socket`, label “TCP sockets”; if it’s HTTP, label HTTP/REST).
- **Hashing/Comparison**: “checksum/hash compare” (MD5/SHA—confirm in code)
- **Deployment**: “Cloud node(s), private IP for Server2”

- the port numbers
- the transport (TCP/UDP/HTTP)
- message format (JSON? pickle? raw bytes?)
- whether Server1 is multi-threaded or sequential (affects concurrency annotations)

##### Server1 compares + returns result

This is often the “most accurate” way to express distributed logic without over-assuming internals.

##### Don’t overthink it: split into as many concrete components as possible
- “Listener/Request Handler” inside Server1
- “Replica Comparator” inside Server1
- “Replica Query Handler” inside Server2
- “Serializer/Protocol codec” (from common.py) used by all
- “Checksum/Hash function” (from common.py) used by servers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ==========================================================
    %% Replica File Comparison - Distributed Systems Assignment
    %% Vertically oriented architecture + deployment boundaries
    %% ==========================================================

    %% ---------------------- External Actor ----------------------
    User["User / Operator"]:::external

    %% ---------------------- Client Side -------------------------
    subgraph "Client Machine (Public/Client Network)"
        ClientProc["Client Process\n(client.py)\n- CLI request initiator\n- Sends compare request\n- Receives match/mismatch"]:::client
    end

    %% ---------------------- Cloud / Servers ----------------------
    subgraph "Cloud Deployment"
        direction TB

        subgraph "Cloud VM #1 (Public Endpoint)"
            S1Proc["Server1 Process\n(server1.py)\nCoordinator / Primary\n- Listens for client\n- Reads local replica\n- Calls Server2 by private IP"]:::server
            subgraph "Server1 Internal Components"
                S1Listener["Listener / Request Handler"]:::component
                S1Comparator["Replica Comparator\n(checksum/metadata compare)"]:::component
                S1Codec["Protocol Codec\n(serialize/deserialize)"]:::component
                S1Hash["Checksum/Hash Utils"]:::component
            end
            S1Store[("Local Replica Store\n(Filesystem)")]:::storage
        end

        subgraph "Private Cloud Subnet (Internal Network)"
            direction TB

            subgraph "Cloud VM #2 (Private IP Only)"
                S2Proc["Server2 Process\n(server2.py)\nReplica / Secondary\n- Serves replica info\n- Reads local replica\n- Responds to Server1"]:::server
                subgraph "Server2 Internal Components"
                    S2Handler["Replica Query Handler"]:::component
                    S2Codec["Protocol Codec\n(serialize/deserialize)"]:::component
                    S2Hash["Checksum/Hash Utils"]:::component
                end
                S2Store[("Local Replica Store\n(Filesystem)")]:::storage
            end
        end

        Readme["Run / Deployment Instructions\n(README.md)\n- Start order\n- Server2 private IP configured in Server1"]:::doc
    end

    %% ---------------------- Shared Module ------------------------
    Common["Shared Library\n(common.py)\n- Message schema/constants\n- Serialization helpers\n- Checksum/hash routines\n- Socket helpers"]:::shared

    %% ---------------------- Primary Flows ------------------------
    User -->|"runs"| ClientProc

    ClientProc -->|"CompareRequest(filename|file_id|bytes|checksum)"| S1Proc
    S1Proc -->|"CompareResponse(match|mismatch|details)"| ClientProc

    %% Server1 reads local replica state
    S1Proc -->|"read_file/metadata"| S1Store
    S1Store -->|"bytes/mtime"| S1Proc

    %% Server1 initiates private connection to Server2 (private IP)
    S1Proc -->|"ReplicaQuery(file_id|checksum_request|fetch)"| S2Proc
    S2Proc -->|"ReplicaInfo(checksum|metadata|optional_bytes)"| S1Proc

    %% Server2 reads local replica state
    S2Proc -->|"read_file/metadata"| S2Store
    S2Store -->|"bytes/mtime"| S2Proc

    %% ---------------------- Internal Wiring (illustrative) ------------------------
    S1Proc -->|"dispatch"| S1Listener
    S1Listener -->|"parse_request"| S1Codec
    S1Codec -->|"decode"| S1Comparator
    S1Comparator -->|"uses"| S1Hash

    S2Proc -->|"dispatch"| S2Handler
    S2Handler -->|"parse_request"| S2Codec
    S2Codec -->|"uses"| S2Hash

    %% ---------------------- Shared Utilities Usage -------------------------------
    Common -.->|"imports"| ClientProc
    Common -.->|"imports"| S1Proc
    Common -.->|"imports"| S2Proc

    Common -.->|"protocol+hashing"| S1Codec
    Common -.->|"hashing"| S1Hash
    Common -.->|"protocol+hashing"| S2Codec
    Common -.->|"hashing"| S2Hash

    Readme -.->|"documents_startup+private_IP_config"| S1Proc
    Readme -.->|"documents_startup"| S2Proc
    Readme -.->|"documents_usage"| ClientProc

    %% ---------------------- Click Events (mapped paths) --------------------------
    click ClientProc "https://github.com/gchinar/gp33-distributed-computing-assignment1/blob/main/client.py"
    click S1Proc "https://github.com/gchinar/gp33-distributed-computing-assignment1/blob/main/server1.py"
    click S2Proc "https://github.com/gchinar/gp33-distributed-computing-assignment1/blob/main/server2.py"
    click Common "https://github.com/gchinar/gp33-distributed-computing-assignment1/blob/main/common.py"
    click Readme "https://github.com/gchinar/gp33-distributed-computing-assignment1/blob/main/README.md"

    %% ---------------------- Styles ----------------------------------------------
    classDef external fill:#111827,stroke:#374151,color:#F9FAFB,stroke-width:1.5px
    classDef client fill:#0B3B82,stroke:#1D4ED8,color:#FFFFFF,stroke-width:1.5px
    classDef server fill:#14532D,stroke:#22C55E,color:#ECFDF5,stroke-width:1.5px
    classDef component fill:#064E3B,stroke:#34D399,color:#ECFDF5,stroke-width:1px
    classDef storage fill:#7C2D12,stroke:#FB923C,color:#FFF7ED,stroke-width:1.5px
    classDef shared fill:#4C1D95,stroke:#A78BFA,color:#F5F3FF,stroke-width:1.5px
    classDef doc fill:#7A0212,stroke:#FB7185,color:#FFF1F2,stroke-width:1.5px
```
