# cs144/imp architecture

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

- Interactive diagram: https://gitdiagram.com/cs144/imp
- Repository: https://github.com/cs144/imp
- Video tour (about a minute): https://gitdiagram.com/cs144/imp/video

## Overview

This is a Stanford CS 144 networking lab repository: a collection of networking exercises and runtime primitives, not a finished networking product. The clearest implemented workflow is `tcp_native`: a user selects client or listen mode, the program connects or accepts a TCP peer, then copies bytes bidirectionally between the socket and standard input/output. The bounded `ByteStream` and event loop support that copy path, though the stream implementation shown is still stubbed. Packet-format and raw-network components are present in the tree, but their wiring is not established by the sampled source; those links are omitted.

Main entry points: [`util/file_descriptor.cc`](https://github.com/cs144/imp/blob/main/util/file_descriptor.cc) (File descriptors), [`apps/bidirectional_stream_copy.cc`](https://github.com/cs144/imp/blob/main/apps/bidirectional_stream_copy.cc) (Bidirectional copy), [`apps/tcp_native.cc`](https://github.com/cs144/imp/blob/main/apps/tcp_native.cc) (TCP client/server), [`src/byte_stream.cc`](https://github.com/cs144/imp/blob/main/src/byte_stream.cc) (Bounded byte stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Applications"]
  node_tcp_native["TCP client/server<br/>[tcp_native.cc]"]
  node_stream_copy["Bidirectional copy"]
  node_webget["Web fetch exercise<br/>[webget.cc]"]
  node_ip_raw["Raw IP exercise<br/>[ip_raw.cc]"]
end

subgraph group_streams["Byte streams"]
  node_byte_stream["Bounded byte stream<br/>[byte_stream.cc]"]
  node_stream_helpers["Stream helpers"]
end

subgraph group_runtime["I/O runtime"]
  node_event_loop["Event loop<br/>[eventloop.cc]"]
  node_file_descriptor["File descriptors<br/>[file_descriptor.cc]"]
  node_socket["Socket operations<br/>[socket.cc]"]
end

subgraph group_network["Network primitives"]
  node_address["Socket addresses<br/>[address.cc]"]
  node_parser["Parser and serializer<br/>[parser.cc]"]
  node_ipv4_header["IPv4 header<br/>[ipv4_header.cc]"]
  node_packet_formats["Packet formats"]
  node_tun["TUN interface<br/>[tun.cc]"]
end

node_user(("User"))
node_stdin(("Standard input"))
node_stdout(("Standard output"))
node_peer(("TCP peer"))

node_user -->|"chooses mode"| node_tcp_native
node_tcp_native -->|"resolves peer"| node_address
node_tcp_native -->|"connects or accepts"| node_socket
node_tcp_native -->|"starts copy"| node_stream_copy
node_peer -->|"TCP connection"| node_socket
node_stream_copy -->|"registers I/O rules"| node_event_loop
node_stream_copy -->|"buffers bytes"| node_byte_stream
node_stream_copy -->|"reads and writes"| node_file_descriptor
node_stream_copy -->|"reads and writes"| node_socket
node_stdin -->|"provides input"| node_file_descriptor
node_file_descriptor -->|"input bytes"| node_byte_stream
node_byte_stream -->|"output bytes"| node_file_descriptor
node_file_descriptor -->|"writes output"| node_stdout
node_event_loop -->|"polls readiness"| node_file_descriptor
node_stream_helpers -->|"reads from"| node_byte_stream
node_ipv4_header -->|"parses fields"| node_parser
node_ipv4_header -->|"serializes fields"| node_parser

click node_tcp_native "https://github.com/cs144/imp/blob/main/apps/tcp_native.cc"
click node_stream_copy "https://github.com/cs144/imp/blob/main/apps/bidirectional_stream_copy.cc"
click node_webget "https://github.com/cs144/imp/blob/main/apps/webget.cc"
click node_ip_raw "https://github.com/cs144/imp/blob/main/apps/ip_raw.cc"
click node_byte_stream "https://github.com/cs144/imp/blob/main/src/byte_stream.cc"
click node_stream_helpers "https://github.com/cs144/imp/blob/main/src/byte_stream_helpers.cc"
click node_event_loop "https://github.com/cs144/imp/blob/main/util/eventloop.cc"
click node_file_descriptor "https://github.com/cs144/imp/blob/main/util/file_descriptor.cc"
click node_socket "https://github.com/cs144/imp/blob/main/util/socket.cc"
click node_address "https://github.com/cs144/imp/blob/main/util/address.cc"
click node_parser "https://github.com/cs144/imp/blob/main/util/parser.cc"
click node_ipv4_header "https://github.com/cs144/imp/blob/main/util/ipv4_header.cc"
click node_packet_formats "https://github.com/cs144/imp/tree/main/util"
click node_tun "https://github.com/cs144/imp/blob/main/util/tun.cc"

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_tcp_native,node_stream_copy,node_webget,node_ip_raw,node_user toneBlue
class node_byte_stream,node_stream_helpers toneAmber
class node_event_loop,node_file_descriptor,node_socket toneMint
class node_address,node_parser,node_ipv4_header,node_packet_formats,node_tun toneRose
class node_stdin,node_stdout,node_peer toneIndigo
```

## Components

### Applications

- [TCP client/server](https://github.com/cs144/imp/blob/main/apps/tcp_native.cc): `apps/tcp_native.cc`
- [Bidirectional copy](https://github.com/cs144/imp/blob/main/apps/bidirectional_stream_copy.cc): `apps/bidirectional_stream_copy.cc`
- [Web fetch exercise](https://github.com/cs144/imp/blob/main/apps/webget.cc): `apps/webget.cc`
- [Raw IP exercise](https://github.com/cs144/imp/blob/main/apps/ip_raw.cc): `apps/ip_raw.cc`

### Byte streams

- [Bounded byte stream](https://github.com/cs144/imp/blob/main/src/byte_stream.cc): `src/byte_stream.cc`
- [Stream helpers](https://github.com/cs144/imp/blob/main/src/byte_stream_helpers.cc): `src/byte_stream_helpers.cc`

### I/O runtime

- [Event loop](https://github.com/cs144/imp/blob/main/util/eventloop.cc): `util/eventloop.cc`
- [File descriptors](https://github.com/cs144/imp/blob/main/util/file_descriptor.cc): `util/file_descriptor.cc`
- [Socket operations](https://github.com/cs144/imp/blob/main/util/socket.cc): `util/socket.cc`

### Network primitives

- [Socket addresses](https://github.com/cs144/imp/blob/main/util/address.cc): `util/address.cc`
- [Parser and serializer](https://github.com/cs144/imp/blob/main/util/parser.cc): `util/parser.cc`
- [IPv4 header](https://github.com/cs144/imp/blob/main/util/ipv4_header.cc): `util/ipv4_header.cc`
- [Packet formats](https://github.com/cs144/imp/tree/main/util): `util`
- [TUN interface](https://github.com/cs144/imp/blob/main/util/tun.cc): `util/tun.cc`

### Other components

- **User**
- **Standard input**
- **Standard output**
- **TCP peer**

## Connections

- User → TCP client/server: chooses mode
- TCP client/server → Socket addresses: resolves peer
- TCP client/server → Socket operations: connects or accepts
- TCP client/server → Bidirectional copy: starts copy
- TCP peer → Socket operations: TCP connection
- Bidirectional copy → Event loop: registers I/O rules
- Bidirectional copy → Bounded byte stream: buffers bytes
- Bidirectional copy → File descriptors: reads and writes
- Bidirectional copy → Socket operations: reads and writes
- Standard input → File descriptors: provides input
- File descriptors → Bounded byte stream: input bytes
- Bounded byte stream → File descriptors: output bytes
- File descriptors → Standard output: writes output
- Event loop → File descriptors: polls readiness
- Stream helpers → Bounded byte stream: reads from
- IPv4 header → Parser and serializer: parses fields
- IPv4 header → Parser and serializer: serializes fields