# hassaanmasood-051/server-client-project architecture

> Architecture diagram of the GitHub repository hassaanmasood-051/server-client-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hassaanmasood-051/server-client-project
- Repository: https://github.com/hassaanmasood-051/server-client-project

## Overview

This repository implements a time-travel debugger: a user starts a debugging session for source code, the client uploads it through a load balancer, and a server produces a trace file that the client reads locally for stepping and inspection. The server includes source resolution, binary conversion, execution, snapshot/timeline handling, and trace serialization; the load balancer queues and relays requests and can wake the server. The README is empty, and some server orchestration is outside the excerpts, so those links are marked unverified rather than asserted.

Main entry points: [`client.cpp`](https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp) (Trace request and download), [`load_balancer.cpp`](https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp) (Stream relay), [`server.cpp`](https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp) (Request handling), [`helper.h`](https://github.com/hassaanmasood-051/server-client-project/blob/main/helper.h) (Checksum and trailer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Debugger client"]
  node_client_cli["Command interface<br/>[client.cpp]"]
  node_client_session["Session and navigation<br/>[client.cpp]"]
  node_client_transfer["Trace request and download<br/>[client.cpp]"]
  node_client_reader["Trace file reader<br/>[client.cpp]"]
  node_client_display["Snapshot display<br/>[client.cpp]"]
end

subgraph group_routing["Request routing"]
  node_lb_accept["Connection acceptor<br/>[load_balancer.cpp]"]
  node_lb_queue["Pending client queue<br/>[load_balancer.cpp]"]
  node_lb_dispatch["Request dispatcher<br/>[load_balancer.cpp]"]
  node_lb_wakeup["Server wakeup<br/>[load_balancer.cpp]"]
  node_lb_relay["Stream relay<br/>[load_balancer.cpp]"]
end

subgraph group_server["Trace server"]
  node_server_ingest["Request handling<br/>[server.cpp]"]
  node_resolver["Source resolver<br/>[server.cpp]"]
  node_binary_converter["Binary converter<br/>[server.cpp]"]
  node_vm["Program executor<br/>[server.cpp]"]
  node_timeline["Snapshot timeline<br/>[server.cpp]"]
  node_trace_writer["Trace serializer<br/>[server.cpp]"]
end

subgraph group_shared["Shared protocol"]
  node_checksum["Checksum and trailer<br/>[helper.h]"]
end

node_user(("Debugger user"))
node_source["Source program"]
node_trace_file["Downloaded trace"]

node_user -->|"enters commands"| node_client_cli
node_client_cli -->|"dispatches commands"| node_client_session
node_client_session -->|"starts trace request"| node_client_transfer
node_client_transfer -->|"uploads source"| node_lb_accept
node_source -->|"provides source"| node_client_transfer
node_lb_accept -->|"enqueues clients"| node_lb_queue
node_lb_dispatch -->|"dequeues clients"| node_lb_queue
node_lb_dispatch -->|"ensures server"| node_lb_wakeup
node_lb_dispatch -->|"serves client"| node_lb_relay
node_lb_wakeup -->|"connects or starts"| node_server_ingest
node_lb_relay -->|"forwards request"| node_server_ingest
node_server_ingest -.->|"processes source"| node_resolver
node_resolver -.->|"prepares resolved code"| node_binary_converter
node_binary_converter -.->|"provides executable code"| node_vm
node_vm -.->|"records snapshots"| node_timeline
node_timeline -.->|"supplies snapshots"| node_trace_writer
node_trace_writer -.->|"returns trace"| node_lb_relay
node_lb_relay -->|"relays response"| node_client_transfer
node_client_transfer -->|"saves download"| node_trace_file
node_client_session -->|"opens trace"| node_client_reader
node_client_session -->|"reads selected step"| node_client_reader
node_client_reader -->|"returns snapshot"| node_client_display
node_client_display -.->|"shows program state"| node_user
node_client_transfer -->|"checks transfer"| node_checksum
node_lb_relay -->|"checks forwarded stream"| node_checksum
node_server_ingest -.->|"validates received data"| node_checksum

click node_client_cli "https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp"
click node_client_session "https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp"
click node_client_transfer "https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp"
click node_client_reader "https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp"
click node_client_display "https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp"
click node_lb_accept "https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp"
click node_lb_queue "https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp"
click node_lb_dispatch "https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp"
click node_lb_wakeup "https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp"
click node_lb_relay "https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp"
click node_server_ingest "https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp"
click node_resolver "https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp"
click node_binary_converter "https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp"
click node_vm "https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp"
click node_timeline "https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp"
click node_trace_writer "https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp"
click node_checksum "https://github.com/hassaanmasood-051/server-client-project/blob/main/helper.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_cli,node_client_session,node_client_transfer,node_client_reader,node_client_display,node_user toneBlue
class node_lb_accept,node_lb_queue,node_lb_dispatch,node_lb_wakeup,node_lb_relay toneAmber
class node_server_ingest,node_resolver,node_binary_converter,node_vm,node_timeline,node_trace_writer toneMint
class node_checksum toneRose
class node_source,node_trace_file toneIndigo
```

## Components

### Debugger client

- [Command interface](https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp): `client.cpp`
- [Session and navigation](https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp): `client.cpp`
- [Trace request and download](https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp): `client.cpp`
- [Trace file reader](https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp): `client.cpp`
- [Snapshot display](https://github.com/hassaanmasood-051/server-client-project/blob/main/client.cpp): `client.cpp`

### Request routing

- [Connection acceptor](https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp): `load_balancer.cpp`
- [Pending client queue](https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp): `load_balancer.cpp`
- [Request dispatcher](https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp): `load_balancer.cpp`
- [Server wakeup](https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp): `load_balancer.cpp`
- [Stream relay](https://github.com/hassaanmasood-051/server-client-project/blob/main/load_balancer.cpp): `load_balancer.cpp`

### Trace server

- [Request handling](https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp): `server.cpp`
- [Source resolver](https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp): `server.cpp`
- [Binary converter](https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp): `server.cpp`
- [Program executor](https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp): `server.cpp`
- [Snapshot timeline](https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp): `server.cpp`
- [Trace serializer](https://github.com/hassaanmasood-051/server-client-project/blob/main/server.cpp): `server.cpp`

### Shared protocol

- [Checksum and trailer](https://github.com/hassaanmasood-051/server-client-project/blob/main/helper.h): `helper.h`

### Other components

- **Debugger user**
- **Source program**
- **Downloaded trace**

## Connections

- Debugger user → Command interface: enters commands (evidence: `client.cpp`)
- Command interface → Session and navigation: dispatches commands (evidence: `client.cpp`)
- Session and navigation → Trace request and download: starts trace request (evidence: `client.cpp`)
- Trace request and download → Connection acceptor: uploads source (evidence: `client.cpp`)
- Source program → Trace request and download: provides source (evidence: `client.cpp`)
- Connection acceptor → Pending client queue: enqueues clients (evidence: `load_balancer.cpp`)
- Request dispatcher → Pending client queue: dequeues clients (evidence: `load_balancer.cpp`)
- Request dispatcher → Server wakeup: ensures server (evidence: `load_balancer.cpp`)
- Request dispatcher → Stream relay: serves client (evidence: `load_balancer.cpp`)
- Server wakeup → Request handling: connects or starts (evidence: `load_balancer.cpp`)
- Stream relay → Request handling: forwards request (evidence: `load_balancer.cpp`)
- Request handling → Source resolver: processes source (evidence: `server.cpp`)
- Source resolver → Binary converter: prepares resolved code (evidence: `server.cpp`)
- Binary converter → Program executor: provides executable code (evidence: `server.cpp`)
- Program executor → Snapshot timeline: records snapshots (evidence: `server.cpp`)
- Snapshot timeline → Trace serializer: supplies snapshots (evidence: `server.cpp`)
- Trace serializer → Stream relay: returns trace
- Stream relay → Trace request and download: relays response (evidence: `load_balancer.cpp`)
- Trace request and download → Downloaded trace: saves download (evidence: `client.cpp`)
- Session and navigation → Trace file reader: opens trace (evidence: `client.cpp`)
- Session and navigation → Trace file reader: reads selected step (evidence: `client.cpp`)
- Trace file reader → Snapshot display: returns snapshot (evidence: `client.cpp`)
- Snapshot display → Debugger user: shows program state
- Trace request and download → Checksum and trailer: checks transfer (evidence: `client.cpp`)
- Stream relay → Checksum and trailer: checks forwarded stream (evidence: `load_balancer.cpp`)
- Request handling → Checksum and trailer: validates received data (evidence: `server.cpp`)
