# dqsjqian/mira architecture

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

- Interactive diagram: https://gitdiagram.com/dqsjqian/mira
- Repository: https://github.com/dqsjqian/mira

## Overview

Mira is a C++23 coroutine networking library, not an application framework. Its principal workflow is for an application to compose an asynchronous transport with an optional TLS layer and a protocol implementation, then exchange data with a peer. Core provides the shared execution and stream contracts; transport handles TCP, UDP, and DNS; protocol stages cover HTTP/1, WebSocket, HTTP/2, and QUIC/HTTP/3. README capabilities are included where implementation excerpts were unavailable; those unsampled areas are not given speculative internal call links.

Main entry points: [`modules/core/include/mira/core/stream.hpp`](https://github.com/dqsjqian/mira/blob/main/modules/core/include/mira/core/stream.hpp) (Async stream contract), [`modules/tls/include/mira/tls/stream.hpp`](https://github.com/dqsjqian/mira/blob/main/modules/tls/include/mira/tls/stream.hpp) (TLS stream), [`modules/transport/include/mira/transport/tcp.hpp`](https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/tcp.hpp) (TCP sockets and listener), [`modules/http3/include/mira/http3/engine.hpp`](https://github.com/dqsjqian/mira/blob/main/modules/http3/include/mira/http3/engine.hpp) (HTTP/3 engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_runtime["Tasks and event loop<br/>[event_loop.hpp]"]
  node_async_stream["Async stream contract<br/>[stream.hpp]"]
end

subgraph group_transport["Transport"]
  node_tcp["TCP sockets and listener<br/>[tcp.hpp]"]
  node_udp["UDP datagrams<br/>[udp.hpp]"]
  node_resolver["DNS resolver<br/>[resolver.hpp]"]
  node_server["Bounded TCP serving<br/>[server.hpp]"]
end

subgraph group_security["Security"]
  node_tls_context["TLS context<br/>[context.hpp]"]
  node_tls_stream["TLS stream<br/>[stream.hpp]"]
  node_tls_engine["TLS state machine<br/>[engine.hpp]"]
  node_crypto["Crypto utilities<br/>[crypto.hpp]"]
end

subgraph group_protocols["Protocols"]
  node_quic["QUIC engine<br/>[engine.hpp]"]
  node_quic_listener["QUIC listener<br/>[listener.hpp]"]
end

subgraph group_web["Web protocols"]
  node_http1["HTTP/1 parsing and service<br/>[parser.hpp]"]
  node_http_client["HTTP client<br/>[client.hpp]"]
  node_ws["WebSocket protocol<br/>[connection.hpp]"]
  node_http2["HTTP/2 sessions<br/>[session.hpp]"]
  node_http3["HTTP/3 engine<br/>[engine.hpp]"]
  node_http3_server["HTTP/3 server<br/>[server.hpp]"]
end

node_app(("Application"))
node_peer(("Network peer"))

node_app -.->|"composes"| node_runtime
node_app -.->|"composes"| node_tcp
node_app -.->|"composes"| node_udp
node_app -.->|"composes"| node_http1
node_app -.->|"composes"| node_tls_stream
node_runtime -->|"supports"| node_async_stream
node_tcp -->|"implements"| node_async_stream
node_tls_stream -->|"implements"| node_async_stream
node_tls_stream -->|"drives"| node_tls_engine
node_tls_stream -->|"uses"| node_tls_context
node_tls_stream -->|"wraps"| node_tcp
node_tls_context -.->|"uses"| node_crypto
node_http1 -->|"uses"| node_async_stream
node_http_client -->|"uses"| node_async_stream
node_ws -->|"uses"| node_async_stream
node_http2 -->|"adapts"| node_async_stream
node_server -->|"accepts"| node_tcp
node_resolver -->|"resolves names"| node_peer
node_tcp -->|"exchanges bytes"| node_peer
node_udp -->|"exchanges datagrams"| node_peer
node_quic_listener -->|"creates connections"| node_quic
node_quic -->|"uses datagrams"| node_udp
node_http3 -->|"owns transport"| node_quic
node_http3_server -->|"dispatches"| node_quic_listener
node_http3_server -->|"creates sessions"| node_http3
node_http3 -->|"exchanges HTTP/3"| node_peer

click node_runtime "https://github.com/dqsjqian/mira/blob/main/modules/core/include/mira/core/event_loop.hpp"
click node_async_stream "https://github.com/dqsjqian/mira/blob/main/modules/core/include/mira/core/stream.hpp"
click node_tcp "https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/tcp.hpp"
click node_udp "https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/udp.hpp"
click node_resolver "https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/resolver.hpp"
click node_server "https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/server.hpp"
click node_tls_context "https://github.com/dqsjqian/mira/blob/main/modules/tls/include/mira/tls/context.hpp"
click node_tls_stream "https://github.com/dqsjqian/mira/blob/main/modules/tls/include/mira/tls/stream.hpp"
click node_tls_engine "https://github.com/dqsjqian/mira/blob/main/modules/tls/include/mira/tls/engine.hpp"
click node_crypto "https://github.com/dqsjqian/mira/blob/main/modules/crypto/include/mira/crypto/crypto.hpp"
click node_http1 "https://github.com/dqsjqian/mira/blob/main/modules/http/include/mira/http/parser.hpp"
click node_http_client "https://github.com/dqsjqian/mira/blob/main/modules/http/include/mira/http/client.hpp"
click node_ws "https://github.com/dqsjqian/mira/blob/main/modules/ws/include/mira/ws/connection.hpp"
click node_http2 "https://github.com/dqsjqian/mira/blob/main/modules/http2/include/mira/http2/session.hpp"
click node_quic "https://github.com/dqsjqian/mira/blob/main/modules/quic/include/mira/quic/engine.hpp"
click node_quic_listener "https://github.com/dqsjqian/mira/blob/main/modules/quic/include/mira/quic/listener.hpp"
click node_http3 "https://github.com/dqsjqian/mira/blob/main/modules/http3/include/mira/http3/engine.hpp"
click node_http3_server "https://github.com/dqsjqian/mira/blob/main/modules/http3/include/mira/http3/server.hpp"

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_runtime,node_async_stream toneBlue
class node_tcp,node_udp,node_resolver,node_server toneAmber
class node_tls_context,node_tls_stream,node_tls_engine,node_crypto toneMint
class node_quic,node_quic_listener toneRose
class node_http1,node_http_client,node_ws,node_http2,node_http3,node_http3_server,node_app,node_peer toneIndigo
```

## Components

### Core runtime

- [Tasks and event loop](https://github.com/dqsjqian/mira/blob/main/modules/core/include/mira/core/event_loop.hpp): `modules/core/include/mira/core/event_loop.hpp`
- [Async stream contract](https://github.com/dqsjqian/mira/blob/main/modules/core/include/mira/core/stream.hpp): `modules/core/include/mira/core/stream.hpp`

### Transport

- [TCP sockets and listener](https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/tcp.hpp): `modules/transport/include/mira/transport/tcp.hpp`
- [UDP datagrams](https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/udp.hpp): `modules/transport/include/mira/transport/udp.hpp`
- [DNS resolver](https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/resolver.hpp): `modules/transport/include/mira/transport/resolver.hpp`
- [Bounded TCP serving](https://github.com/dqsjqian/mira/blob/main/modules/transport/include/mira/transport/server.hpp): `modules/transport/include/mira/transport/server.hpp`

### Security

- [TLS context](https://github.com/dqsjqian/mira/blob/main/modules/tls/include/mira/tls/context.hpp): `modules/tls/include/mira/tls/context.hpp`
- [TLS stream](https://github.com/dqsjqian/mira/blob/main/modules/tls/include/mira/tls/stream.hpp): `modules/tls/include/mira/tls/stream.hpp`
- [TLS state machine](https://github.com/dqsjqian/mira/blob/main/modules/tls/include/mira/tls/engine.hpp): `modules/tls/include/mira/tls/engine.hpp`
- [Crypto utilities](https://github.com/dqsjqian/mira/blob/main/modules/crypto/include/mira/crypto/crypto.hpp): `modules/crypto/include/mira/crypto/crypto.hpp`

### Protocols

- [QUIC engine](https://github.com/dqsjqian/mira/blob/main/modules/quic/include/mira/quic/engine.hpp): `modules/quic/include/mira/quic/engine.hpp`
- [QUIC listener](https://github.com/dqsjqian/mira/blob/main/modules/quic/include/mira/quic/listener.hpp): `modules/quic/include/mira/quic/listener.hpp`

### Web protocols

- [HTTP/1 parsing and service](https://github.com/dqsjqian/mira/blob/main/modules/http/include/mira/http/parser.hpp): `modules/http/include/mira/http/parser.hpp`
- [HTTP client](https://github.com/dqsjqian/mira/blob/main/modules/http/include/mira/http/client.hpp): `modules/http/include/mira/http/client.hpp`
- [WebSocket protocol](https://github.com/dqsjqian/mira/blob/main/modules/ws/include/mira/ws/connection.hpp): `modules/ws/include/mira/ws/connection.hpp`
- [HTTP/2 sessions](https://github.com/dqsjqian/mira/blob/main/modules/http2/include/mira/http2/session.hpp): `modules/http2/include/mira/http2/session.hpp`
- [HTTP/3 engine](https://github.com/dqsjqian/mira/blob/main/modules/http3/include/mira/http3/engine.hpp): `modules/http3/include/mira/http3/engine.hpp`
- [HTTP/3 server](https://github.com/dqsjqian/mira/blob/main/modules/http3/include/mira/http3/server.hpp): `modules/http3/include/mira/http3/server.hpp`

### Other components

- **Application**
- **Network peer**

## Connections

- Application → Tasks and event loop: composes
- Application → TCP sockets and listener: composes
- Application → UDP datagrams: composes
- Application → HTTP/1 parsing and service: composes
- Application → TLS stream: composes
- Tasks and event loop → Async stream contract: supports
- TCP sockets and listener → Async stream contract: implements
- TLS stream → Async stream contract: implements
- TLS stream → TLS state machine: drives
- TLS stream → TLS context: uses
- TLS stream → TCP sockets and listener: wraps
- TLS context → Crypto utilities: uses
- HTTP/1 parsing and service → Async stream contract: uses
- HTTP client → Async stream contract: uses
- WebSocket protocol → Async stream contract: uses
- HTTP/2 sessions → Async stream contract: adapts
- Bounded TCP serving → TCP sockets and listener: accepts
- DNS resolver → Network peer: resolves names
- TCP sockets and listener → Network peer: exchanges bytes
- UDP datagrams → Network peer: exchanges datagrams
- QUIC listener → QUIC engine: creates connections
- QUIC engine → UDP datagrams: uses datagrams
- HTTP/3 engine → QUIC engine: owns transport
- HTTP/3 server → QUIC listener: dispatches
- HTTP/3 server → HTTP/3 engine: creates sessions
- HTTP/3 engine → Network peer: exchanges HTTP/3