# zhuhaow/nekit architecture

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

- Interactive diagram: https://gitdiagram.com/zhuhaow/nekit
- Repository: https://github.com/zhuhaow/nekit

## Overview

##### Project type and purpose
- NEKit is an open-source Swift library (deprecated) that implements a custom networking “stack” and proxy framework for iOS and macOS.
- It provides low-level components (raw sockets, DNS, TCP/UDP stacks, proxy servers, tunnel abstraction, rule engine, crypto utilities) intended for building VPN-like or proxy apps.

##### File structure
- Top-level targets:
- NEKit-iOS and NEKit-macOS frameworks (Objective-C headers & Info.plist)
- NEKitDemo app (macOS/iOS demo)
- Test folders for unit specs
- Core library under src/:
- Config (parsers, configuration model)
- Crypto (HMAC, MD5, Libsodium wrappers, stream crypto)
- GeoIP (country lookup)
- Event (observer pattern for logging/debug events)
- IPStack (DNS, packet parsing, router, TUN interface, TCP/UDP stacks)
- RawSocket (platform-specific socket factories for TCP/UDP, TUN)
- ProxyServer (HTTP, SOCKS5, generic GCD server)
- Socket adapters (AdapterSocket: factories for HTTP/SOCKS5/Shadowsocks, direct, speed test, reject)
- ProxySocket (client-side proxy protocols)
- Tunnel (abstract queue/tunnel for chained proxies)
- Rule (domain/IP/country rules, manager)
- Utils (scanners, buffers, IP types, atomic, checksums…)
- ResponseGenerator (to craft HTTP/SOCKS5 responses)

##### README for additional insights
- Author notes the library houses many patterns (factories, observer) but lacks an ideal architecture.
- Emphasis on developer understanding of I/O, packet flow, concurrency (GCD).

1) Demo App (entry point)
2) NEKit Framework (shared code)
– Configuration Layer
– Rule Engine
– Event Dispatcher
– GeoIP Service
– Crypto Module
– ProxyServer Module
– IPStack Module (DNS Resolver, Packet Parser, Router, TCP/UDP Stacks, TUN Interface)
– RawSocket Layer (GCD/NW sockets, TUN socket factory)
– Socket Adapter Layer (AdapterSocket factories & adapters)
– ProxySocket Layer (client-side proxies)
– Tunnel Abstraction
– ResponseGenerator Factory
– Utilities
– Demo App → Configuration (load rules, adapter settings)
– Configuration → Rule Engine (construct RuleManager)
– Rule Engine → Router (rule matching per packet/connection)
– Router → Tunnel (decide direct or chain through proxy adapters)
– Tunnel → Socket Adapter Layer → RawSocket Layer (establish socket or TUN interface)
– For inbound DNS: IPStack.DNS Resolver → RawSocket → Packet Parser → Router
– ProxyServer Module (listening servers) → RawSocket Layer → ProxySocket Layer → Rule Engine → ResponseGenerator → Event Dispatcher
– Crypto Module used by ShadowsocksAdapter & HMAC utilities in adapter layer
– Event Dispatcher observes significant events across modules (proxy connections, rule matches, errors)
– GeoIP consulted by CountryRule during rule matching
c. Architectural patterns & principles
– Factory pattern heavily in AdapterSocketFactory, RawSocketFactory, ResponseGeneratorFactory
– Observer pattern in Event/ObserverFactory
– Single Responsibility: each subfolder handles a cohesive concern
– Layered design: Configuration → Rule → Routing → Transport → Socket → OS
– Protocol-oriented Swift (protocols for Stack, Packet, Socket)
d. Key technologies & frameworks
– Swift (source code)
– Grand Central Dispatch (GCD) for concurrency
– Network framework (NWTCPSocket, NWUDPSocket)
– CommonCrypto or Libsodium for crypto
– Apple’s NetworkExtension API (when used by demo app or in host app)

##### Details to capture
- Platform targets (iOS vs macOS frameworks) can be side-by-side or combined under “NEKit Framework.”
- Demo App linking against NEKit-iOS/macOS.
- Call out test suite as a separate, nonproduction component.
- How the TUN interface slot sits between IPStack and RawSocket.

## Diagram (Mermaid)

```mermaid
flowchart TD
    DemoApp["Demo App"]:::external
    subgraph "NEKit Framework"
        direction TB
        Config["Configuration Layer"]:::core
        RuleEngine["Rule Engine"]:::core
        EventDispatcher["Event Dispatcher"]:::core
        GeoIP["GeoIP Service"]:::core
        Crypto["Crypto Module"]:::core
        subgraph "IPStack Module"
            direction TB
            DNSResolver["DNS Resolver"]:::core
            PacketParser["Packet Parser"]:::core
            Router["Router"]:::core
            TCPUDP["TCP/UDP Stacks"]:::core
            TUNInterface["TUN Interface"]:::core
        end
        RawSocket["RawSocket Layer"]:::core
        ProxyServer["ProxyServer Module"]:::core
        AdapterSocket["Socket Adapter Layer"]:::ext
        ProxySocket["ProxySocket Layer"]:::ext
        Tunnel["Tunnel Abstraction"]:::ext
        ResponseGen["ResponseGenerator Factory"]:::ext
        Utils["Utilities"]:::util
    end
    TestSuite["Test Suites"]:::util

    %% Data/Control flows
    DemoApp -->|"loadConfig()"| Config
    Config -->|"parseRules()"| RuleEngine
    RuleEngine -->|"matchRule()"| Router
    Router -->|"route()"| Tunnel
    Tunnel -->|"createSocket()"| AdapterSocket
    AdapterSocket -->|"createRaw()"| RawSocket
    DNSResolver -->|"send()"| RawSocket
    RawSocket -->|"receive()"| PacketParser
    PacketParser -->|"parsed()"| Router
    ProxyServer -->|"listen()"| RawSocket
    RawSocket -->|"accepted()"| ProxySocket
    ProxySocket -->|"applyRules()"| RuleEngine
    ProxyServer -->|"generateResponse()"| ResponseGen
    ResponseGen -->|"emitEvent()"| EventDispatcher
    Crypto -->|"usedBy()"| AdapterSocket
    GeoIP -->|"lookup()"| RuleEngine
    EventDispatcher -.->|".observe()"| Config
    EventDispatcher -.->|".observe()"| RuleEngine
    EventDispatcher -.->|".observe()"| ProxyServer
    EventDispatcher -.->|".observe()"| Tunnel
    Utils -->|".assist()"| Config

    DemoApp --> TestSuite

    %% Click Events
    click DemoApp "https://github.com/zhuhaow/nekit/tree/master/NEKitDemo/"
    click Config "https://github.com/zhuhaow/nekit/tree/master/src/Config/"
    click RuleEngine "https://github.com/zhuhaow/nekit/tree/master/src/Rule/"
    click EventDispatcher "https://github.com/zhuhaow/nekit/tree/master/src/Event/"
    click GeoIP "https://github.com/zhuhaow/nekit/blob/master/src/GeoIP/GeoIP.swift"
    click Crypto "https://github.com/zhuhaow/nekit/tree/master/src/Crypto/"
    click DNSResolver "https://github.com/zhuhaow/nekit/tree/master/src/IPStack/DNS/"
    click PacketParser "https://github.com/zhuhaow/nekit/tree/master/src/IPStack/Packet/"
    click Router "https://github.com/zhuhaow/nekit/blob/master/src/IPStack/Router.swift"
    click TCPUDP "https://github.com/zhuhaow/nekit/blob/master/src/IPStack/TCPStack.swift"
    click TUNInterface "https://github.com/zhuhaow/nekit/blob/master/src/IPStack/TUNInterface.swift"
    click RawSocket "https://github.com/zhuhaow/nekit/tree/master/src/RawSocket/"
    click ProxyServer "https://github.com/zhuhaow/nekit/tree/master/src/ProxyServer/"
    click AdapterSocket "https://github.com/zhuhaow/nekit/tree/master/src/Socket/AdapterSocket/"
    click ProxySocket "https://github.com/zhuhaow/nekit/tree/master/src/Socket/ProxySocket/"
    click Tunnel "https://github.com/zhuhaow/nekit/tree/master/src/Tunnel/"
    click ResponseGen "https://github.com/zhuhaow/nekit/blob/master/src/ResponseGeneratorFactory.swift"
    click Utils "https://github.com/zhuhaow/nekit/tree/master/src/Utils/"
    click TestSuite "https://github.com/zhuhaow/nekit/tree/master/test/"

    %% Styles
    classDef core fill:#B3D4FC,stroke:#0366d6,color:#000
    classDef ext fill:#C6E5B3,stroke:#22863a,color:#000
    classDef util fill:#EDEDED,stroke:#959DA5,color:#000
    classDef external fill:#FEEFB3,stroke:#8A6D3B,color:#000
```
