# zio/zio-http architecture

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

- Interactive diagram: https://gitdiagram.com/zio/zio-http
- Repository: https://github.com/zio/zio-http

## Overview

##### Core Components
- Core HTTP Engine: Highlight the “zio-http” module as the central piece, which includes the “HTTP as function” abstraction. This is where request → response functions, routing, middleware wrapping, and error handling live.
- Platform-Specific Implementations: Show separate branches (or layers) for platform-specific code:
– JVM-specific parts (under zio-http/jvm) that use Netty for server features.
– JS-specific parts (under zio-http/js) for client/driver implementations.
– Shared functionality (under zio-http/shared) that is common between platforms.
- Supporting Modules: Include adjunct modules such as:
– zio-http-cli (providing command-line HTTP client/server handling).
– zio-http-docs (for generating documentation and references).
– zio-http-gen (for code generation related to endpoints, OpenAPI specs, gRPC integration, etc.).
– zio-http-benchmarks and profiling modules (for performance testing and profiling).
– Testkit modules (like zio-http-testkit) to enable testing without a live server instance.
– Example modules (zio-http-example) to demonstrate usage patterns.

##### Relationships and Interactions
- Dependencies: Indicate that the core library depends on ZIO (the underlying effect system) and on Netty in the JVM implementation.
- Middleware Connections: Detail how middleware components are ‘wrapped’ around endpoints—for handling logging, metrics, auth, etc.
- Endpoint Composition: Represent the separation between endpoint definitions (declarative descriptions) and their associated execution logic.
- Integration Points: Include integrations like JSON and binary codecs (enabled through built-in ZIO Schema or dedicated codec modules), as well as OpenAPI and WebSocket support.

##### Architectural Patterns and Principles
- Functional Core / Imperative Shell: Emphasize the “HTTP as function” concept by showing how HTTP endpoints are represented as pure functions. This illustrates the type-driven, composable pattern of the architecture.
- Modular Design: Demonstrate the dependency inversion and modular layering, with clear separation between core functionality, platform-specific adapters, and external utilities (testing, CLI, documentation).
- Extensibility: Represent extension points such as middleware hooks and endpoint generators (from openapi or grpc tools).

##### Relevant Technologies and Frameworks
- ZIO: Note the core dependency on ZIO for effect management, concurrency, resource management, and composability.
- Netty: In the server layer (especially in the JVM submodule), highlight the relationship to Netty for handling low-level network IO.
- Build/CI Infrastructure: Possible extra “infrastructure” component representing the SBT build, GitHub workflows, and documentation generation (through modules like docs/ and the .devcontainer settings) to capture how the project is maintained.

##### Being Detailed
- Don’t be shy about splitting the architecture into as many components as possible. For instance, separately represent the typical processing pipeline: Request Parsing → Routing → Handler Execution → Response Generation.
- Ancillary modules like “zio-http-gen” (depicted as an endpoint/code generator that takes, say, a schema and outputs concrete endpoint code), “zio-http-cli” (a separate entry point for command-line interactions), and so on.
- Error handling and fallback middleware as part of the pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Engine Layer"
        coreEngine["Core HTTP Engine"]
    end

    subgraph "Platform-Specific Implementations"
        jvmImpl["JVM-Specific HTTP Implementation (Netty Integration)"]
        jsImpl["JS-Specific HTTP Implementation"]
    end

    subgraph "Supporting Modules"
        cli["HTTP CLI Tooling"]
        docs["Documentation & OpenAPI"]
        codegen["Code Generation for Endpoints/OpenAPI/GRPC"]
        benchmarks["Performance Benchmarking & Profiling"]
        testkit["Testing Utilities (Testkit)"]
        example["Example Usage & Demos"]
    end

    subgraph "External Dependencies"
        zio["ZIO"]
        netty["Netty"]
    end

    %% External Dependencies
    coreEngine -->|"uses"| zio
    jvmImpl -->|"uses"| netty

    %% Core Engine Integration with Platform-Specific Implementations
    coreEngine -->|"adapts_to"| jvmImpl
    coreEngine -->|"adapts_to"| jsImpl

    %% Bi-directional Client/Server Interaction
    jvmImpl <-->|"HTTP_exchange"| jsImpl

    %% Supporting Modules Integration with Core Engine
    cli -->|"CLI_calls"| coreEngine
    docs -->|"Docs_for"| coreEngine
    codegen -->|"Generates_for"| coreEngine
    benchmarks -->|"Benchmarks"| coreEngine
    testkit -->|"Tests_with"| coreEngine
    example -->|"Demos_usage"| coreEngine

    %% Click Events
    click coreEngine "https://github.com/zio/zio-http/tree/main/zio-http/shared"
    click jvmImpl "https://github.com/zio/zio-http/tree/main/zio-http/jvm"
    click jsImpl "https://github.com/zio/zio-http/tree/main/zio-http/js"
    click cli "https://github.com/zio/zio-http/tree/main/zio-http-cli"
    click docs "https://github.com/zio/zio-http/tree/main/zio-http-docs"
    click codegen "https://github.com/zio/zio-http/tree/main/zio-http-gen"
    click benchmarks "https://github.com/zio/zio-http/tree/main/zio-http-benchmarks"
    click testkit "https://github.com/zio/zio-http/tree/main/zio-http-testkit"
    click example "https://github.com/zio/zio-http/tree/main/zio-http-example"

    %% Styles
    classDef core fill:#f4e1d2,stroke:#b58900,stroke-width:2px;
    classDef platform fill:#d0eac9,stroke:#859900,stroke-width:2px;
    classDef support fill:#cfe8fc,stroke:#268bd2,stroke-width:2px;
    classDef external fill:#fde2e4,stroke:#d33682,stroke-width:2px;

    class coreEngine core;
    class jvmImpl,jsImpl platform;
    class cli,docs,codegen,benchmarks,testkit,example support;
    class zio,netty external;
```
