# aspirant200715/onyx architecture

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

- Interactive diagram: https://gitdiagram.com/aspirant200715/onyx
- Repository: https://github.com/aspirant200715/onyx

## Overview

#### Purpose and Workspace

Onyx is a first-principles Rust web framework at Tier 1: a raw TCP HTTP/1.1 server, routing, request extraction, response conversion, and typed errors. The workspace manifest is `Cargo.toml`; implementation is under `onyx/crates/`.

Its public application-facing entry point is the core crate prelude/API in `onyx/crates/ember-core/src/lib.rs`. A minimal server usage example is `onyx/crates/ember-core/examples/hello_tcp.rs`.

#### HTTP Foundation

`ember-http` owns HTTP protocol models and parsing, independent of application routing:

- Request and response representations: `onyx/crates/ember-http/src/request.rs`, `onyx/crates/ember-http/src/response.rs`
- HTTP primitives—methods, statuses, headers, and versions: `onyx/crates/ember-http/src/method.rs`, `onyx/crates/ember-http/src/status.rs`, `onyx/crates/ember-http/src/headers.rs`
- Incremental parsing boundary for raw request bytes: `onyx/crates/ember-http/src/parser/request.rs`, `onyx/crates/ember-http/src/parser/request_line.rs`

This crate is the protocol boundary between TCP input and a typed HTTP request.

#### TCP Server and Dispatch

The runtime server is implemented in `onyx/crates/ember-core/src/server.rs`. It accepts raw TCP traffic, invokes the HTTP parser, then hands parsed requests to routing/handler dispatch. The framework is Rust-native and appears to use direct TCP rather than an external HTTP server, async runtime, reverse proxy, database, or cloud service.

Errors crossing server, routing, and handler boundaries are centralized in `onyx/crates/ember-core/src/error.rs`, with HTTP-layer errors separately represented in `onyx/crates/ember-http/src/error.rs`.

#### Routing and Path Resolution

Routing maps an HTTP method and request path to a handler:

- Route representation and registration: `onyx/crates/ember-core/src/route.rs`
- Router/dispatch coordination: `onyx/crates/ember-core/src/router.rs`
- Static/dynamic segment matching and parameter capture: `onyx/crates/ember-core/src/path_matcher.rs`, `onyx/crates/ember-core/src/path.rs`

Control flow is request → router → matching route → handler. Dynamic path captures become input for extraction rather than requiring handlers to parse URLs directly.

#### Handler Input Extraction

Core request extractors isolate handler code from raw HTTP structures:

- Extractor abstraction: `onyx/crates/ember-core/src/extractor.rs`
- Path and query decoding: `onyx/crates/ember-core/src/path.rs`, `onyx/crates/ember-core/src/query.rs`
- Typed header access: `onyx/crates/ember-core/src/header.rs`

Handlers can receive framework request data and expose failures through result-based error handling, rather than manually validating all transport input.

#### Response and Error Conversion

Handler outputs are normalized through responder abstractions:

- Generic responder contract and conversions: `onyx/crates/ember-core/src/responder.rs`
- JSON response support: `onyx/crates/ember-core/src/json.rs`
- HTTP response construction/status output: `onyx/crates/ember-http/src/response.rs`, `onyx/crates/ember-http/src/status.rs`

The outgoing flow is handler return value or `EmberError` → responder/error mapping → HTTP response → TCP write.

#### Cross-Cutting Extension Points

Middleware is organized as a core pipeline extension point, with current authentication and logging modules at `onyx/crates/ember-core/src/middleware/mod.rs`, `onyx/crates/ember-core/src/middleware/auth.rs`, and `onyx/crates/ember-core/src/middleware/logger.rs`.

`onyx/crates/ember-macros/src/lib.rs` is a separate procedural-macro crate, providing compile-time ergonomic extension capability without coupling macro implementation to the HTTP/runtime layers.

Main entry points: [`onyx/crates/ember-core/src/router.rs`](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/router.rs) (Router & Dispatch), [`onyx/crates/ember-core/src/server.rs`](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/server.rs) (TCP Server), [`onyx/crates/ember-core/src/responder.rs`](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/responder.rs) (Responder Conversion), [`onyx/crates/ember-http/src/parser/request.rs`](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/parser/request.rs) (Incremental Request Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP Foundation"]
  node_http_parser["Incremental Request Parser<br/>[request.rs]"]
  node_request_line["Request-Line Parser<br/>parser stage<br/>[request_line.rs]"]
  node_http_request["HTTP Request Model<br/>protocol model<br/>[request.rs]"]
  node_http_primitives["HTTP Primitives<br/>protocol types<br/>[method.rs]"]
  node_http_response["HTTP Response Model<br/>protocol model<br/>[response.rs]"]
end

subgraph group_core["Core Runtime"]
  node_app_api["Public API &amp; Prelude<br/>crate entry<br/>[lib.rs]"]
  node_example["Hello TCP Example<br/>example app<br/>[hello_tcp.rs]"]
  node_tcp_server["TCP Server<br/>runtime server<br/>[server.rs]"]
  node_router["Router &amp; Dispatch<br/>routing coordinator<br/>[router.rs]"]
  node_routes["Route Registration<br/>route model<br/>[route.rs]"]
  node_path_matching["Path Matching &amp; Captures<br/>matcher<br/>[path_matcher.rs]"]
  node_extractors["Extractor Contract<br/>handler input<br/>[extractor.rs]"]
  node_query_input["Query Decoding<br/>extractor<br/>[query.rs]"]
  node_typed_headers["Typed Header Access<br/>extractor<br/>[header.rs]"]
  node_middleware["Middleware Pipeline<br/>extension point<br/>[mod.rs]"]
  node_responder["Responder Conversion<br/>output contract<br/>[responder.rs]"]
  node_json["JSON Responses<br/>response conversion<br/>[json.rs]"]
  node_errors["Core Errors<br/>error boundary<br/>[error.rs]"]
end

subgraph group_extensions["Compile-time Extensions"]
  node_macros{{"Procedural Macros<br/>macro crate<br/>[lib.rs]"}}
end

node_example -->|"uses"| node_app_api
node_app_api -->|"starts"| node_tcp_server
node_tcp_server -->|"raw TCP bytes"| node_http_parser
node_http_parser -->|"parses"| node_request_line
node_http_parser -->|"produces"| node_http_request
node_http_primitives -->|"defines fields"| node_http_request
node_tcp_server -->|"dispatches request"| node_router
node_router -->|"selects"| node_routes
node_router -->|"matches path"| node_path_matching
node_path_matching -->|"path captures"| node_extractors
node_extractors -.->|"includes"| node_query_input
node_extractors -.->|"includes"| node_typed_headers
node_middleware -->|"wraps dispatch"| node_router
node_router -->|"handler result"| node_responder
node_json -->|"implements conversion"| node_responder
node_responder -->|"builds"| node_http_response
node_http_response -->|"TCP write"| node_tcp_server
node_errors -->|"error response mapping"| node_responder
node_http_primitives -->|"status and headers"| node_http_response
node_macros -.->|"ergonomic extensions"| node_app_api

click node_app_api "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/lib.rs"
click node_example "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/examples/hello_tcp.rs"
click node_tcp_server "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/server.rs"
click node_http_parser "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/parser/request.rs"
click node_request_line "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/parser/request_line.rs"
click node_http_request "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/request.rs"
click node_http_primitives "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/method.rs"
click node_router "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/router.rs"
click node_routes "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/route.rs"
click node_path_matching "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/path_matcher.rs"
click node_extractors "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/extractor.rs"
click node_query_input "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/query.rs"
click node_typed_headers "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/header.rs"
click node_middleware "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/middleware/mod.rs"
click node_responder "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/responder.rs"
click node_json "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/json.rs"
click node_http_response "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/response.rs"
click node_errors "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/error.rs"
click node_macros "https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-macros/src/lib.rs"

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_http_parser,node_request_line,node_http_request,node_http_primitives,node_http_response toneBlue
class node_app_api,node_example,node_tcp_server,node_router,node_routes,node_path_matching,node_extractors,node_query_input,node_typed_headers,node_middleware,node_responder,node_json,node_errors toneAmber
class node_macros toneMint
```

## Components

### HTTP Foundation

Protocol models and incremental request parsing.

- [Incremental Request Parser](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/parser/request.rs): parser · Converts raw request bytes into typed HTTP requests. · `onyx/crates/ember-http/src/parser/request.rs`
- [Request-Line Parser](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/parser/request_line.rs): parser stage · `onyx/crates/ember-http/src/parser/request_line.rs`
- [HTTP Request Model](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/request.rs): protocol model · `onyx/crates/ember-http/src/request.rs`
- [HTTP Primitives](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/method.rs): protocol types · Methods, statuses, headers, and versions. · `onyx/crates/ember-http/src/method.rs`
- [HTTP Response Model](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-http/src/response.rs): protocol model · Constructs outgoing HTTP status and response data. · `onyx/crates/ember-http/src/response.rs`

### Core Runtime

TCP serving, dispatch, routing, and handler extensions.

- [Public API & Prelude](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/lib.rs): crate entry · Application-facing framework entry point. · `onyx/crates/ember-core/src/lib.rs`
- [Hello TCP Example](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/examples/hello_tcp.rs): example app · `onyx/crates/ember-core/examples/hello_tcp.rs`
- [TCP Server](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/server.rs): runtime server · Accepts TCP connections and drives request/response I/O. · `onyx/crates/ember-core/src/server.rs`
- [Router & Dispatch](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/router.rs): routing coordinator · `onyx/crates/ember-core/src/router.rs`
- [Route Registration](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/route.rs): route model · `onyx/crates/ember-core/src/route.rs`
- [Path Matching & Captures](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/path_matcher.rs): matcher · Resolves static and dynamic path segments. · `onyx/crates/ember-core/src/path_matcher.rs`
- [Extractor Contract](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/extractor.rs): handler input · `onyx/crates/ember-core/src/extractor.rs`
- [Query Decoding](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/query.rs): extractor · `onyx/crates/ember-core/src/query.rs`
- [Typed Header Access](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/header.rs): extractor · `onyx/crates/ember-core/src/header.rs`
- [Middleware Pipeline](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/middleware/mod.rs): extension point · Includes authentication and logging middleware. · `onyx/crates/ember-core/src/middleware/mod.rs`
- [Responder Conversion](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/responder.rs): output contract · Normalizes handler return values into HTTP responses. · `onyx/crates/ember-core/src/responder.rs`
- [JSON Responses](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/json.rs): response conversion · `onyx/crates/ember-core/src/json.rs`
- [Core Errors](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-core/src/error.rs): error boundary · Maps server, routing, and handler failures. · `onyx/crates/ember-core/src/error.rs`

### Compile-time Extensions

- [Procedural Macros](https://github.com/aspirant200715/onyx/blob/main/onyx/crates/ember-macros/src/lib.rs): macro crate · Compile-time ergonomic extension capability. · `onyx/crates/ember-macros/src/lib.rs`

## Connections

- Hello TCP Example → Public API & Prelude: uses
- Public API & Prelude → TCP Server: starts
- TCP Server → Incremental Request Parser: raw TCP bytes
- Incremental Request Parser → Request-Line Parser: parses
- Incremental Request Parser → HTTP Request Model: produces
- HTTP Primitives → HTTP Request Model: defines fields
- TCP Server → Router & Dispatch: dispatches request
- Router & Dispatch → Route Registration: selects
- Router & Dispatch → Path Matching & Captures: matches path
- Path Matching & Captures → Extractor Contract: path captures
- Extractor Contract → Query Decoding: includes
- Extractor Contract → Typed Header Access: includes
- Middleware Pipeline → Router & Dispatch: wraps dispatch
- Router & Dispatch → Responder Conversion: handler result
- JSON Responses → Responder Conversion: implements conversion
- Responder Conversion → HTTP Response Model: builds
- HTTP Response Model → TCP Server: TCP write
- Core Errors → Responder Conversion: error response mapping
- HTTP Primitives → HTTP Response Model: status and headers
- Procedural Macros → Public API & Prelude: ergonomic extensions