# danielgtaylor/huma architecture

> Architecture diagram of the GitHub repository danielgtaylor/huma, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danielgtaylor/huma
- Repository: https://github.com/danielgtaylor/huma

## Overview

#### Purpose and entry points
Huma is a Go library/framework for HTTP REST/RPC APIs. It layers typed operation registration, OpenAPI 3.1 generation, JSON Schema generation, validation, serialization, and standardized errors over an application-owned router and server. Consumers typically construct an API through a router adapter, register generic operations, then start `net/http` themselves. Core public surfaces are `huma.go`, `api.go`, and `defaults.go`.

#### API construction and router boundary
The `API` abstraction decouples Huma’s request/response pipeline from routing implementations. Router-specific packages translate route registration and request context behavior for Chi, stdlib Go mux, Gin, Echo, Fiber, Flow, httprouter, mux, and BunRouter:
- `adapters/humachi/humachi.go`
- `adapters/humago/humago.go`
- `adapters/humagin/humagin.go`

This is the principal integration boundary: applications retain their router, middleware, telemetry, and HTTP server lifecycle; Huma owns operation semantics.

#### Operation registration and execution pipeline
Generic registration helpers define an operation’s method, path, metadata, typed input, typed output, and handler. Registration both mounts a runtime route and contributes to the generated API description. At request time, the pipeline binds path/query/header/cookie/body inputs, applies defaults/resolvers, validates, invokes the handler, and serializes typed output or errors:
- `api.go`
- `huma.go`
- `chain.go`

Groups provide shared route prefixes, metadata, and middleware-like composition around sets of operations:
- `group.go`

#### Schema and OpenAPI model
Reflection over annotated Go input/output types produces reusable JSON Schema definitions and OpenAPI operation components. The registry manages schema identity/reuse, while OpenAPI types and generation maintain the externally consumable contract:
- `schema.go`
- `registry.go`
- `openapi.go`

Generated OpenAPI and per-resource schemas support documentation, code generators, mock servers, SDK/CLI tooling, and editor integrations without a separate design artifact.

#### Input validation and error boundary
Request parsing and validation enforce typed parameters, body constraints, and schema annotations before application handlers execute. Failures are converted to API error responses, defaulting to RFC 9457 `application/problem+json`; handlers can return structured errors through the same response boundary:
- `validate.go`
- `validation/messages.go`
- `error.go`

Supporting request concerns include form decoding, cookies, query parsing, and naming conversion:
- `formdata.go`
- `cookie.go`
- `queryparam/queryparam.go`

#### Response negotiation, transforms, and advanced HTTP behavior
Response production selects a registered representation from `Accept`, serializes output, applies transformers, and can stream server-sent events. JSON is the baseline; CBOR is an optional format registered by importing its package. Conditional-request helpers and automatic PATCH operations extend standard operation behavior:
- `negotiation/negotiation.go`
- `transforms.go`
- `sse/sse.go`
- `formats/cbor/cbor.go`
- `conditional/params.go`
- `autopatch/autopatch.go`

#### Runtime tooling and repository infrastructure
`humacli` optionally supplies argument/environment configuration, startup hooks, and graceful lifecycle integration; it does not replace the application’s HTTP server:
- `humacli/humacli.go`

`humatest` supports in-process API testing with the same runtime abstractions:
- `humatest/humatest.go`

The module is Go-based (`go.mod`), with CI, benchmarks, and documentation-site builds managed through GitHub Actions and MkDocs:
- `go.mod`
- `.github/workflows/ci.yaml`
- `docs/mkdocs.yml`

Main entry points: [`huma.go`](https://github.com/danielgtaylor/huma/blob/main/huma.go) (Operation registration), [`transforms.go`](https://github.com/danielgtaylor/huma/blob/main/transforms.go) (Response production), [`chain.go`](https://github.com/danielgtaylor/huma/blob/main/chain.go) (Request pipeline), [`api.go`](https://github.com/danielgtaylor/huma/blob/main/api.go) (API abstraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Application Integration"]
  node_app["Application<br/>consumer"]
  node_adapters{{"Router adapters<br/>adapter packages<br/>[humachi.go]"}}
end

subgraph group_core["Core Runtime"]
  node_api["API abstraction<br/>core interface<br/>[api.go]"]
  node_registration["Operation registration<br/>generic API<br/>[huma.go]"]
  node_groups["Operation groups<br/>composition<br/>[group.go]"]
  node_pipeline["Request pipeline<br/>runtime execution<br/>[chain.go]"]
  node_validation["Input validation<br/>[validate.go]"]
  node_errors["Problem error boundary<br/>error response<br/>[error.go]"]
  node_responses["Response production<br/>serialization<br/>[transforms.go]"]
end

subgraph group_contract["API Contract"]
  node_schema["JSON Schema generation<br/>reflection<br/>[schema.go]"]
  node_registry[("Schema registry<br/>schema catalog<br/>[registry.go]")]
  node_openapi["OpenAPI 3.1 model<br/>API description<br/>[openapi.go]"]
end

subgraph group_extensions["Extensions"]
  node_negotiation["Content negotiation<br/>HTTP negotiation<br/>[negotiation.go]"]
  node_sse["SSE streaming<br/>response extension<br/>[sse.go]"]
  node_cbor["CBOR format<br/>optional format<br/>[cbor.go]"]
  node_advanced["Conditional &amp; PATCH helpers<br/>operation extension<br/>[params.go]"]
  node_cli["humacli<br/>lifecycle tooling<br/>[humacli.go]"]
  node_testkit["humatest<br/>test runtime<br/>[humatest.go]"]
end

node_app -->|"selects router integration"| node_adapters
node_adapters -->|"implements boundary"| node_api
node_app -->|"registers operations"| node_registration
node_registration -->|"mounts routes through"| node_api
node_groups -->|"composes operations"| node_registration
node_registration -->|"creates runtime handler"| node_pipeline
node_registration -->|"contributes operations"| node_openapi
node_registration -->|"reflects typed I/O"| node_schema
node_schema -->|"reuses definitions"| node_registry
node_registry -->|"supplies components"| node_openapi
node_pipeline -->|"validates bound input"| node_validation
node_validation -->|"converts failures"| node_errors
node_pipeline -->|"serializes handler result"| node_responses
node_errors -->|"uses response boundary"| node_responses
node_responses -->|"selects representation"| node_negotiation
node_cbor -.->|"registers format"| node_negotiation
node_sse -.->|"adds streaming output"| node_responses
node_advanced -.->|"extends operations"| node_registration
node_cli -.->|"integrates startup lifecycle"| node_app
node_testkit -.->|"exercises in process"| node_api

click node_adapters "https://github.com/danielgtaylor/huma/blob/main/adapters/humachi/humachi.go"
click node_api "https://github.com/danielgtaylor/huma/blob/main/api.go"
click node_registration "https://github.com/danielgtaylor/huma/blob/main/huma.go"
click node_groups "https://github.com/danielgtaylor/huma/blob/main/group.go"
click node_pipeline "https://github.com/danielgtaylor/huma/blob/main/chain.go"
click node_validation "https://github.com/danielgtaylor/huma/blob/main/validate.go"
click node_errors "https://github.com/danielgtaylor/huma/blob/main/error.go"
click node_responses "https://github.com/danielgtaylor/huma/blob/main/transforms.go"
click node_schema "https://github.com/danielgtaylor/huma/blob/main/schema.go"
click node_registry "https://github.com/danielgtaylor/huma/blob/main/registry.go"
click node_openapi "https://github.com/danielgtaylor/huma/blob/main/openapi.go"
click node_negotiation "https://github.com/danielgtaylor/huma/blob/main/negotiation/negotiation.go"
click node_sse "https://github.com/danielgtaylor/huma/blob/main/sse/sse.go"
click node_cbor "https://github.com/danielgtaylor/huma/blob/main/formats/cbor/cbor.go"
click node_advanced "https://github.com/danielgtaylor/huma/blob/main/conditional/params.go"
click node_cli "https://github.com/danielgtaylor/huma/blob/main/humacli/humacli.go"
click node_testkit "https://github.com/danielgtaylor/huma/blob/main/humatest/humatest.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_adapters toneBlue
class node_api,node_registration,node_groups,node_pipeline,node_validation,node_errors,node_responses toneAmber
class node_schema,node_registry,node_openapi toneMint
class node_negotiation,node_sse,node_cbor,node_advanced,node_cli,node_testkit toneRose
```

## Components

### Application Integration

Application-owned router and server lifecycle.

- **Application**: consumer · Owns router, middleware, and HTTP server.
- [Router adapters](https://github.com/danielgtaylor/huma/blob/main/adapters/humachi/humachi.go): adapter packages · Bridge supported routers to Huma's API abstraction. · `adapters/humachi/humachi.go`

### Core Runtime

Typed operation registration and request execution.

- [API abstraction](https://github.com/danielgtaylor/huma/blob/main/api.go): core interface · Decouples operation semantics from router implementations. · `api.go`
- [Operation registration](https://github.com/danielgtaylor/huma/blob/main/huma.go): generic API · Defines typed operations and mounts runtime routes. · `huma.go`
- [Operation groups](https://github.com/danielgtaylor/huma/blob/main/group.go): composition · Shares prefixes, metadata, and middleware-like behavior. · `group.go`
- [Request pipeline](https://github.com/danielgtaylor/huma/blob/main/chain.go): runtime execution · Binds, resolves, validates, invokes, and serializes. · `chain.go`
- [Input validation](https://github.com/danielgtaylor/huma/blob/main/validate.go): validation · Enforces typed parameters and schema constraints. · `validate.go`
- [Problem error boundary](https://github.com/danielgtaylor/huma/blob/main/error.go): error response · Produces RFC 9457 problem responses. · `error.go`
- [Response production](https://github.com/danielgtaylor/huma/blob/main/transforms.go): serialization · Negotiates representations and applies transformers. · `transforms.go`

### API Contract

Generated OpenAPI and reusable JSON Schema.

- [JSON Schema generation](https://github.com/danielgtaylor/huma/blob/main/schema.go): reflection · Builds schemas from annotated Go types. · `schema.go`
- [Schema registry](https://github.com/danielgtaylor/huma/blob/main/registry.go): schema catalog · Manages reusable schema identity and definitions. · `registry.go`
- [OpenAPI 3.1 model](https://github.com/danielgtaylor/huma/blob/main/openapi.go): API description · Maintains the generated external API contract. · `openapi.go`

### Extensions

Optional runtime behaviors and tooling.

- [Content negotiation](https://github.com/danielgtaylor/huma/blob/main/negotiation/negotiation.go): HTTP negotiation · Selects a registered response representation from Accept. · `negotiation/negotiation.go`
- [SSE streaming](https://github.com/danielgtaylor/huma/blob/main/sse/sse.go): response extension · `sse/sse.go`
- [CBOR format](https://github.com/danielgtaylor/huma/blob/main/formats/cbor/cbor.go): optional format · Registers CBOR as an additional representation. · `formats/cbor/cbor.go`
- [Conditional & PATCH helpers](https://github.com/danielgtaylor/huma/blob/main/conditional/params.go): operation extension · Adds conditional request and automatic PATCH behavior. · `conditional/params.go`
- [humacli](https://github.com/danielgtaylor/huma/blob/main/humacli/humacli.go): lifecycle tooling · Provides configuration, hooks, and graceful lifecycle integration. · `humacli/humacli.go`
- [humatest](https://github.com/danielgtaylor/huma/blob/main/humatest/humatest.go): test runtime · Runs APIs in process through the same abstractions. · `humatest/humatest.go`

## Connections

- Application → Router adapters: selects router integration
- Router adapters → API abstraction: implements boundary
- Application → Operation registration: registers operations
- Operation registration → API abstraction: mounts routes through
- Operation groups → Operation registration: composes operations
- Operation registration → Request pipeline: creates runtime handler
- Operation registration → OpenAPI 3.1 model: contributes operations
- Operation registration → JSON Schema generation: reflects typed I/O
- JSON Schema generation → Schema registry: reuses definitions
- Schema registry → OpenAPI 3.1 model: supplies components
- Request pipeline → Input validation: validates bound input
- Input validation → Problem error boundary: converts failures
- Request pipeline → Response production: serializes handler result
- Problem error boundary → Response production: uses response boundary
- Response production → Content negotiation: selects representation
- CBOR format → Content negotiation: registers format
- SSE streaming → Response production: adds streaming output
- Conditional & PATCH helpers → Operation registration: extends operations
- humacli → Application: integrates startup lifecycle
- humatest → API abstraction: exercises in process
