# halcyonazure/cs144 architecture

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

- Interactive diagram: https://gitdiagram.com/halcyonazure/cs144
- Repository: https://github.com/halcyonazure/cs144

## Overview

##### Project type and purpose
- This is an educational network‐stack implementation in C++ for Stanford’s CS144 labs (2021).
- It provides a reusable library (“libsponge”) that implements TCP/IP primitives (byte streams, packet parsing, TCP sender/receiver, router, taps), plus a suite of small applications (in “apps/”) that exercise the library, and extensive unit and doctests.

##### File structure
- Top‐level
- CMakeLists.txt, cmake-variants.yaml, compile_commands.json: build system using CMake.
- README.md, writeups/: documentation and lab reports.
- assignments/: original PDFs of lab exercises.
- etc/: CMake modules, linting/config, Doxygen config.
- tap.sh, tun.sh, txrx.sh: helper scripts to drive TUN/TAP interfaces.
- libsponge/
- Core modules: byte_stream, network_interface, router, stream_reassembler, tcp_connection.
- tcp_helpers/: low‐level packet formats and helpers for Ethernet, ARP, IPv4, TCP, adapters.
- util/: event loop, socket wrappers, parsers, tun interface.
- apps/: standalone executables demonstrating usage (bidirectional_stream_copy, bouncer, webget, simulators, benchmarks).
- tests/ and doctests/: comprehensive unit tests for each library component.
- No separate “frontend/backend”—this is a protocol library + apps + tests.

##### README insights
- Confirms it’s a hands‐on TCP/IP stack implementation with tests.
- Mentions use of gcc-10, blog writeups.
- Points to original empty “sponge” repo and assignments.

##### Final advice
- Both build‐time (CMake → libsponge → apps/tests) and run‐time (app → library → OS) views.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build Architecture"
        direction TB
        CMake["CMakeLists.txt"]:::build
        subgraph "Libsponge Core Library"
            direction TB
            ByteStream["ByteStream Module"]:::transport
            NetIf["NetworkInterface Module"]:::network
            Router["Router Module"]:::network
            StreamReasm["StreamReassembler Module"]:::transport
            TCPConn["TCPConnection Module"]:::transport
            WrappingInt["Wrapping Integers"]:::transport
        end
        TCPHelpers["TCP/IP Helpers"]:::network
        Util["Utilities (util/)"]:::link
        Apps["Applications (apps/)"]:::application
        Tests["Test Harness (tests/)"]:::test
        CMake -->|builds| ByteStream
        CMake -->|builds| NetIf
        CMake -->|builds| Router
        CMake -->|builds| StreamReasm
        CMake -->|builds| TCPConn
        CMake -->|builds| WrappingInt
        CMake -->|builds| TCPHelpers
        CMake -->|builds| Util
        CMake -->|builds| Apps
        CMake -->|builds| Tests

        click ByteStream "https://github.com/halcyonazure/cs144/blob/master/libsponge/byte_stream.hh"
        click NetIf "https://github.com/halcyonazure/cs144/blob/master/libsponge/network_interface.hh"
        click Router "https://github.com/halcyonazure/cs144/blob/master/libsponge/router.hh"
        click StreamReasm "https://github.com/halcyonazure/cs144/blob/master/libsponge/stream_reassembler.hh"
        click TCPConn "https://github.com/halcyonazure/cs144/blob/master/libsponge/tcp_connection.hh"
        click WrappingInt "https://github.com/halcyonazure/cs144/blob/master/libsponge/wrapping_integers.hh"
        click TCPHelpers "https://github.com/halcyonazure/cs144/tree/master/libsponge/tcp_helpers/"
        click Util "https://github.com/halcyonazure/cs144/tree/master/libsponge/util/"
        click Apps "https://github.com/halcyonazure/cs144/tree/master/apps/"
        click Tests "https://github.com/halcyonazure/cs144/tree/master/tests/"
    end

    subgraph "Runtime Architecture"
        direction TB
        AppExec["App (webget, bouncer, …)"]:::application
        LibAPI["libsponge Public API"]:::transport

        subgraph "Transport Layer"
            direction TB
            TCPConnRT["TCPConnection"]:::transport
            StreamReasmRT["StreamReassembler"]:::transport
            TCPSend["TCP Sender"]:::transport
            TCPRecv["TCP Receiver"]:::transport
        end

        IP["IPv4 Layer"]:::network
        Eth["Ethernet/ARP Layer"]:::link
        Adapter["TUN/Socket Adapter"]:::link
        OS["OS Network Stack"]:::os

        AppExec -->|calls| LibAPI
        LibAPI -->|creates| TCPConnRT
        TCPConnRT -->|uses| StreamReasmRT
        TCPConnRT -->|sends via| TCPSend
        TCPConnRT -->|receives via| TCPRecv
        TCPSend -->|encapsulate| IP
        TCPRecv -->|decapsulate| IP
        IP -->|frame| Eth
        Eth -->|via| Adapter
        Adapter -->|interfaces| OS

        click TCPSend "https://github.com/halcyonazure/cs144/blob/master/libsponge/tcp_sender.hh"
        click TCPRecv "https://github.com/halcyonazure/cs144/blob/master/libsponge/tcp_receiver.hh"
        click Adapter "https://github.com/halcyonazure/cs144/blob/master/libsponge/util/tun.hh"
        click OS "https://github.com/halcyonazure/cs144/blob/master/tap.sh"
    end

    classDef application fill:#9f6,stroke:#333,stroke-width:1px;
    classDef transport fill:#6cf,stroke:#333,stroke-width:1px;
    classDef network fill:#fc6,stroke:#333,stroke-width:1px;
    classDef link fill:#ccc,stroke:#333,stroke-width:1px;
    classDef os fill:#c6f,stroke:#333,stroke-width:1px;
    classDef build fill:#ffeb99,stroke:#333,stroke-width:1px;
    classDef test fill:#f99,stroke:#333,stroke-width:1px,stroke-dasharray:5 5;
```
