docs: restructure architecture documentation and add new guides

docs/architecture/network/network_stack.md

@@ -0,0 +1,52 @@
+# Networking Stack
+
+BoredOS features a robust networking stack capable of handling Ethernet, IPv4, TCP, UDP, ICMP, DHCP, and DNS. The stack is built on top of the **lwIP (Lightweight IP)** library, which is integrated with a custom hardware driver layer.
+
+## 1. Architecture Overview
+
+The network stack is split into three main layers:
+1. **Hardware/Driver Layer (`src/net/nic/`)**: Communicates with physical and virtual Network Interface Cards (NICs), handling raw Ethernet frame transmission and reception. Supported drivers include the Intel E1000 (`e1000.c`), Realtek RTL8139 (`rtl8139.c`), Realtek RTL8111 (`rtl8111.c`), and VirtIO network devices (`virtio_net.c`). A generic interface is provided via `nic.c`.
+2. **Protocol Layer (lwIP)**: Processes Ethernet frames, handles ARP resolution, routes IPv4 packets, and manages TCP state machines.
+3. **OS Interface Layer (`src/net/network.c`)**: Wraps the asynchronous lwIP API into a synchronous, easy-to-use API for BoredOS applications and the kernel.
+
+## 2. Initialization & Polling
+
+### `network_init()`
+When the kernel boots, it initializes the network subsystem by:
+1. Probing the PCI bus for supported NICs (e.g., the Intel E1000).
+2. Initializing the lwIP core (`lwip_init()`) and DNS subsystem.
+3. Binding the hardware NIC to lwIP using `netif_add`.
+4. Automatically attempting to acquire an IP address via DHCP (`network_dhcp_acquire()`).
+
+### The Polling Mechanism (`network_process_frames`)
+Unlike some operating systems that process network packets entirely inside hardware interrupt handlers, BoredOS uses a **polled approach** to avoid re-entrancy issues in the TCP/IP stack. 
+
+The `network_process_frames()` function is called periodically (e.g., from the Window Manager loop or during blocking network calls). It calls:
+- `nic_netif_poll()`: Pulls raw packets from the NIC ring buffer and feeds them to lwIP (`ethernet_input`).
+- `sys_check_timeouts()`: Fires lwIP internal timers for TCP retransmissions, ARP cache expiration, and DHCP lease renewals.
+
+A `network_processing` flag acts as a lightweight spinlock to prevent nested execution of the network poll loop.
+
+## 3. TCP Implementation & Application API
+
+While lwIP provides a callback-based raw API, BoredOS wraps this into a sequential API for userland applications.
+
+Currently, the OS supports **one active TCP connection globally across the entire system**. The connection state is managed via a global Protocol Control Block (`current_tcp_pcb`). To prevent unauthorized cleanup, the OS tracks which process initiated the connection (`tcp_owner_pid`). If a new process attempts to connect while a connection is active, the existing connection is forcefully aborted.
+
+### `network_tcp_connect(ip, port)`
+1. Allocates a new Protocol Control Block (`tcp_new()`).
+2. Registers callbacks for receive (`tcp_recv_callback`), error, and connection success.
+3. Blocks (while polling the network) until the connection succeeds or times out after 15 seconds.
+
+### `network_tcp_recv(buf, max_len)`
+When packets arrive, `tcp_recv_callback` chains them into a `tcp_recv_queue` (`struct pbuf`). 
+The `network_tcp_recv` function blocks until data is available in this queue, then copies it into the application's buffer and frees the `pbuf`. A non-blocking variant (`network_tcp_recv_nb`) is also provided.
+
+### Process Cleanup (`network_cleanup`)
+If an application crashes or exits without closing its socket, the kernel's process manager calls `network_cleanup()`. This checks if the exiting process owns the current TCP PCB (`tcp_owner_pid`) and forcibly aborts the connection to prevent resource leaks.
+
+## 4. Helper Protocols
+
+- **DHCP:** Managed entirely by lwIP. BoredOS simply waits up to 10 seconds during boot for a lease.
+- **DNS (`network_dns_lookup`):** Uses lwIP's `dns_gethostbyname`. It blocks and polls until the callback is triggered with the resolved IP address.
+- **ICMP (Ping):** The kernel provides a `network_icmp_single_ping` function using an lwIP raw socket (`raw_pcb`) to construct, checksum, and transmit an ICMP Echo Request, blocking until a reply is received to calculate the Round-Trip Time (RTT).