# honojs/node-server architecture

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

- Interactive diagram: https://gitdiagram.com/honojs/node-server
- Repository: https://github.com/honojs/node-server

## Overview

##### Project Type & Purpose
- This is a Node.js adapter library (`@hono/node-server`) that lets you run a Hono application on Node.js (v18+).
- It implements a bridge between Node.js core HTTP/HTTP2 APIs and Hono’s Web-standard Request/Response/fetch model.
- It also bundles middleware support (static‐file serving, ConnInfo helper, optional TLS via createServer, overrideGlobalObjects, etc.).

##### File Structure & Architectural Clues
- src/
- index.ts – entry point that re-exports the adapter API (`serve`, `serveStatic`, `getConnInfo`, etc.)
- server.ts, listener.ts – core logic for creating HTTP/HTTP2 server and listening loop.
- request.ts, response.ts – adapter classes mapping Node’s IncomingMessage/ServerResponse ↔ Web Request/Response.
- serve-static.ts – static file middleware implementation (options: root, rewrite, onFound, precompressed).
- conninfo.ts – extracts remote address, port, TLS info.
- globals.ts – logic for overrideGlobalObjects (patching global Request/Response).
- utils.ts, utils/response – helper functions, constants (e.g., RESPONSE_ALREADY_SENT).
- vercel.ts – special entry for Vercel serverless environment.
- Configuration & Scripts: tsup.config.ts (build), jest.config.js (tests), eslint, Prettier, CI workflow.
- test/ – comprehensive tests for each module, static assets for serveStatic.

##### Key Components
a. Developer Application (Hono App)
- Your code that defines routes & middleware via Hono.
b. NodeServer Adapter Layer
- serve() function
- createServer/Listener
- global override module
- ConnInfo helper
- RESPONSE_ALREADY_SENT & utils
c. Node.js Core HTTP/HTTP2 Server
- IncomingMessage & Http2ServerRequest
- ServerResponse & Http2ServerResponse
- Optional TLS configuration via createServer (fs, cert/key)
d. Middleware Subsystems
- Static File Middleware (serveStatic)
- Routing & handler invocation in Hono
e. External Systems
- File system (for static files)
- Vercel serverless platform (vercel.ts entry)

##### Interactions & Data Flow
1. Client HTTP request → Node.js HTTP/HTTP2 Server
2. IncomingMessage/Http2ServerRequest passed to adapter’s listener
3. Adapter constructs Web-standard Request object (using request.ts, optionally overrideGlobal)
4. Adapter invokes Hono’s `fetch(request, env)`
5. Hono router → user-defined route handlers → returns Web Response
6. Adapter converts Web Response → Node.js ServerResponse (using response.ts / utils/response)
7. ServerResponse sent back to client
8. If static route → serveStatic middleware reads from file system, applies rewrite/onFound/precompressed, returns Response

##### Architectural Patterns & Principles
- Adapter Pattern: decouples Node.js core APIs from Web API used by Hono
- Middleware Pipeline: static file middleware, routing, error handling
- Single Responsibility: separate modules for request conversion, response conversion, static serve, connection info
- Pluggable Configuration: overrideGlobalObjects, autoCleanupIncoming, createServer injection

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Hono Application"
        HA["Hono App"]:::app
    end

    %% Adapter Layer
    subgraph "NodeServer Adapter"
        idx["Adapter Entry & APIs"]:::adapter
        srv["HTTP/HTTP2 Server Creation & TLS"]:::adapter
        lst["Server Listener Loop"]:::adapter
        req["Request Conversion"]:::adapter
        resConv["Response Conversion"]:::adapter
        glob["Global Object Overrides"]:::adapter
        ci["Connection Info Helper"]:::adapter
        util["Core Utility Functions"]:::adapter
        utilRes["Response Utilities"]:::adapter
        utilResConst["Response Constants"]:::adapter
        stm["Static File Middleware"]:::adapter
        types["Shared Type Definitions"]:::adapter
    end

    %% Alternate Entry
    subgraph "Alternate Entry"
        ver["Vercel Serverless Entry"]:::external
    end

    %% Core HTTP/HTTP2
    subgraph "Node.js Core HTTP/HTTP2"
        NM["IncomingMessage<br/>Http2ServerRequest"]:::core
        SR["ServerResponse<br/>Http2ServerResponse"]:::core
        TLS["Optional TLS (cert/key)"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        FS["File System (Static Files)"]:::external
        Vercel["Vercel Platform"]:::external
    end

    %% Request Flow
    NM --> lst
    TLS --> srv
    srv --> lst
    lst --> req
    lst --> ci
    req -->|"invoke fetch(request, env)"| HA
    HA --> resConv
    resConv --> SR

    %% Static Middleware Flow
    req -->|"static route"| stm
    stm --> FS
    FS --> stm
    stm --> resConv

    %% Alternate Vercel Flow
    ver --> req

    %% Global Overrides Path
    idx -->|"overrideGlobalObjects=true"| glob
    glob --> req
    idx --> req

    %% Utilities Connections
    lst --> util
    resConv --> utilRes
    utilRes --> utilResConst
    lst --> types
    req --> types
    resConv --> types
    stm --> types

    %% Subgraph Relationships
    idx --> srv
    idx --> stm
    idx --> ver
    idx --> lst
    idx --> ci

    %% Click Events
    click idx "https://github.com/honojs/node-server/blob/main/src/index.ts"
    click srv "https://github.com/honojs/node-server/blob/main/src/server.ts"
    click lst "https://github.com/honojs/node-server/blob/main/src/listener.ts"
    click req "https://github.com/honojs/node-server/blob/main/src/request.ts"
    click resConv "https://github.com/honojs/node-server/blob/main/src/response.ts"
    click glob "https://github.com/honojs/node-server/blob/main/src/globals.ts"
    click ci "https://github.com/honojs/node-server/blob/main/src/conninfo.ts"
    click util "https://github.com/honojs/node-server/blob/main/src/utils.ts"
    click utilRes "https://github.com/honojs/node-server/blob/main/src/utils/response.ts"
    click utilResConst "https://github.com/honojs/node-server/blob/main/src/utils/response/constants.ts"
    click stm "https://github.com/honojs/node-server/blob/main/src/serve-static.ts"
    click ver "https://github.com/honojs/node-server/blob/main/src/vercel.ts"
    click types "https://github.com/honojs/node-server/blob/main/src/types.ts"

    %% Styles
    classDef adapter fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef core fill:#DFFFD6,stroke:#22863A,stroke-width:1px;
    classDef app fill:#FFEFD6,stroke:#D97706,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#6A737D,stroke-width:1px;
```
