# wangyu-/tinyportmapper architecture

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

- Interactive diagram: https://gitdiagram.com/wangyu-/tinyportmapper
- Repository: https://github.com/wangyu-/tinyportmapper

## Overview

##### Project type and purpose
- This is a single-process, event-driven, high-performance port forwarding utility written in C/C++. It uses an embedded copy of libev (a Reactor/event-loop library) to multiplex socket I/O and forwards traffic bidirectionally between a local listener and a remote endpoint for both TCP and UDP.

##### File structure
- Top-level source modules
- main.cpp           – entry point, CLI parsing, configuration setup
- common.cpp/.h      – helper utilities (e.g., address parsing, error reporting)
- fd_manager.cpp/.h  – tracks active sockets and their state (maps FDs to connection objects)
- my_ev.cpp/.h       – wrapper layer on top of libev (initializes the event loop, registers callbacks)
- Third-party library directory
- libev/             – embedded Reactor implementation (ev.c/.h, backends for epoll, select, etc.)
- Build artifacts
- makefile           – orchestrates compilation of all modules, builds one binary
- configure/autogen – libev’s autotools scripts (only relevant if re-configuring libev)

##### README for additional insights
- Confirms the core architecture is an event-loop (epoll on Linux) that demultiplexes socket events and dispatches read/write handlers.
- Supports both TCP and UDP forwarding, IPv4/IPv6, and configurable socket buffers and logging options.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External systems
    Clients(["Clients"]):::external
    RemoteServers(["Remote Servers"]):::external

    %% Process subgraph
    subgraph "Process" 
        direction TB
        Parser["CLI Parser"]:::parser
        Config["Configuration Object"]:::parser
        Reactor["Reactor/Event Loop\n(my_ev + libev)"]:::core
        FDMgr["FD Manager"]:::core
        TCP["TCP Forwarder"]:::tcp
        UDP["UDP Forwarder"]:::udp
        Common["Common Utilities"]:::common
        Logger["Logger"]:::logger
        Build["Build Automation\n(makefile)"]:::build
        subgraph "Autotools Scripts"
            direction TB
            A1["autogen.sh"]:::build
            A2["configure.ac"]:::build
            A3["Makefile.am"]:::build
        end
    end

    %% Initialization flow
    Parser -->|"init()"| Config
    Config -->|"setup Reactor"| Reactor

    %% Reactor and FD Manager registration
    Reactor <-->|"register FD"| FDMgr

    %% Protocol handlers registration
    Reactor -->|"accept()"| TCP
    TCP -->|"read()/write()"| RemoteServers
    Clients -->|"TCP Connect"| TCP

    Reactor -->|"recvfrom()"| UDP
    UDP -->|"sendto()/recvfrom()"| RemoteServers
    Clients -->|"UDP Datagram"| UDP

    %% Utilities usage
    Common --> Parser
    Common --> Reactor
    Common --> FDMgr
    Common --> TCP
    Common --> UDP

    %% Logging calls
    Parser -->|"log()"| Logger
    Config -->|"log()"| Logger
    Reactor -->|"log()"| Logger
    FDMgr -->|"log()"| Logger
    TCP -->|"log()"| Logger
    UDP -->|"log()"| Logger
    Common -->|"log()"| Logger

    %% Build and autotools
    Build --> A1
    Build --> A2
    Build --> A3

    %% External styling
    classDef external fill:#ade8f4,stroke:#0077b6,stroke-width:2px;
    classDef parser fill:#90e0ef,stroke:#0077b6;
    classDef core fill:#b8f2e6,stroke:#009e66;
    classDef tcp fill:#ffba08,stroke:#ff8f00;
    classDef udp fill:#ffd60a,stroke:#e08500;
    classDef common fill:#d3d3d3,stroke:#6c757d;
    classDef logger fill:#ffadad,stroke:#d00000,shape:triangle;
    classDef build fill:#cdb4db,stroke:#5a189a;

    %% Click events
    click Parser "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/main.cpp"
    click Config "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/main.cpp"
    click Reactor "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/my_ev.cpp"
    click Reactor "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/my_ev.h"
    click Reactor "https://github.com/wangyu-/tinyportmapper/tree/branch_libev/libev/"
    click FDMgr "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/fd_manager.cpp"
    click FDMgr "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/fd_manager.h"
    click Logger "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/log.cpp"
    click Logger "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/log.h"
    click Common "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/common.cpp"
    click Common "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/common.h"
    click Build "https://github.com/wangyu-/tinyportmapper/tree/branch_libev/makefile"
    click A1 "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/libev/autogen.sh"
    click A2 "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/libev/configure.ac"
    click A3 "https://github.com/wangyu-/tinyportmapper/blob/branch_libev/libev/Makefile.am"
```
