# nubskr/networkio architecture

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

- Interactive diagram: https://gitdiagram.com/nubskr/networkio
- Repository: https://github.com/nubskr/networkio

## Overview

##### Project Type and Purpose
- The project is essentially a networking library/application that guarantees at least once message delivery.
- It provides functions to initialize connections (via InitConnection) and continuously accept connections on a listening port (via AcceptConnRequestLoop).
- It encapsulates core abstractions such as a Connection object that provides read/write methods and a Dispatcher that queues and processes events.
- Given the presence of a cmd/ directory with a main.go file, there’s likely an entry point for bootstrapping the service, while the networkio package contains the core logic and APIs.

##### Analyzing the File Structure
- Top-Level Files: README.md, go.mod, and go.sum indicate a Go project with module management.
- cmd/networkio/main.go: This is the command-line entry point used to run the network I/O service.
- The networkio directory contains essential files such as:
– exposed_apis.go: Likely includes the public API functions (e.g., InitConnection, AcceptConnRequestLoop).
– dispacher.go: Implements the event dispatching mechanism (receiving, queuing, and processing events).
– event.go: Defines the structure of an Event, which packages connection IDs and messages.
– init.go & init_test.go: Initialization routines and corresponding tests.
– main.go: May serve as an alternative entry point or orchestrator within the library.
- This structure suggests a clean separation between the application’s executable entry point (cmd) and the core networking logic (networkio).

##### Identifying the Main Components
- Client/Connection Initiator:
- Functions like InitConnection(addr, port, ourId) return a Connection object.
- Connection Acceptor:
- AcceptConnRequestLoop (running as a Go routine) listens on port 8080 to create Connection objects upon incoming connection requests.
- Core Connection Object:
- Encapsulates methods such as WriteToConn and ReadFromConn.
- Contains logic for handling IO blocking and failure scenarios (with mechanisms using select statements and channels for graceful shutdown).
- Dispatcher:
- Responsible for queuing Event objects (each containing a connection ID and a Message) and dispatching events to call connection.writeToConn.
- Acts as an intermediary layer that hands off events to the appropriate connection based on conn_id.
- Connection Manager (implied by the existence of GetConnFromConnId API):
- Manages and retrieves Connection objects, mapping connection IDs to their respective Connection objects.
- Testing / Reliability Mechanism:
- Tests that validate multiple handshake scenarios and ensure that, despite potential delayed ACKs, the reliable delivery guarantee is maintained.
- Special attention to error handling in read/write loops using connectionDead channels and select statements.

##### Detailing Relationships and Interactions
- How the application’s main entry (cmd/networkio/main.go) calls the exposed APIs in networkio.
- AcceptConnRequestLoop running as a background routine that continuously listens for incoming connections and creates Connection objects upon receipt.
- Dispatcher as a component that receives Event objects (packaging conn_ids and messages) and interacts with the Connection Manager to retrieve the correct Connection object for writing data.
- Error handling flows:
- If the ReadFromConn loop fails (indicating a broken connection), it triggers retry logic and closes the connectionDead channel.
- This in turn causes any blocked writing routines inside a select block or inner loop to gracefully exit.

##### Architectural Patterns & Technologies
- Concurrency Model: Emphasize the use of Go routines to implement independent, asynchronous read and write loops for handling IO.
- Event-Driven Architecture: The Dispatcher uses an event queue to decouple message receipt from processing and sending.
- Resilience and Retry Logic: Highlight how the design guarantees message delivery even when one part of the connection pipeline (e.g., the write loop waiting on IO) is blocked.
- Separation of Concerns: Clearly separate network connection management, event dispatching, and API exposure as distinct modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes with classes
    M["Main (cmd/networkio)"]:::entry
    L["Internal Library Orchestration"]:::entry
    AP["Exposed APIs (InitConnection,AcceptConnRequestLoop)"]:::api
    CI["Connection Initializer"]:::api
    CT["Initialization Tests"]:::api
    CA["Connection Acceptor/Listener"]:::api
    CO["Connection Object (Read/Write loops)"]:::core
    CM["Connection Manager (GetConnFromConnId)"]:::core
    DP["Dispatcher (Event Queue)"]:::dispatcher
    EV["Event (conn_id,message)"]:::event
    EH["Error Handling & Retry (connectionDead)"]:::core

    %% Flows and relationships
    M -->|"calls"| AP
    L -->|"orchestrates"| AP
    AP -->|"invokes"| CI
    AP -->|"invokes"| CA
    CI -->|"creates"| CO
    CA -->|"creates"| CO
    CI -->|"tests"| CT
    CO -->|"sends_events"| DP
    DP -->|"queues"| EV
    EV -->|"maps_connection"| CM
    CM -->|"retrieves"| CO
    CO -->|"on_failure"| EH
    EH -->|"triggers_shutdown"| CO

    %% Click Events
    click M "https://github.com/nubskr/networkio/blob/main/cmd/networkio/main.go"
    click L "https://github.com/nubskr/networkio/blob/main/networkio/main.go"
    click AP "https://github.com/nubskr/networkio/blob/main/networkio/exposed_apis.go"
    click CI "https://github.com/nubskr/networkio/blob/main/networkio/init.go"
    click CT "https://github.com/nubskr/networkio/blob/main/networkio/init_test.go"
    click DP "https://github.com/nubskr/networkio/blob/main/networkio/dispacher.go"
    click EV "https://github.com/nubskr/networkio/blob/main/networkio/event.go"

    %% Styles
    classDef entry fill:#f9a,stroke:#333,stroke-width:2px;
    classDef api fill:#ccf,stroke:#333,stroke-width:2px;
    classDef core fill:#cfc,stroke:#333,stroke-width:2px;
    classDef dispatcher fill:#fc9,stroke:#333,stroke-width:2px;
    classDef event fill:#cff,stroke:#333,stroke-width:2px;
```
