---
status: draft
last_updated: 2026-09-10
---

# alktls — Architecture

The authoritative architecture spec for the alktls crate (Phase 1 of
the SDD process). All docs are **Draft** pending the architecture
review pass; statuses update here as docs advance.

All docs follow the SDD process conventions: specs reference ADRs and
OQs by number, ADRs explain WHY, `open-questions.md` tracks what is
unresolved.

## Documents

| Doc | Status | Scope |
|-----|--------|-------|
| [overview.md](overview.md) | Draft | Purpose, transport picture, API surface, ADR/OQ index |
| [server.md](server.md) | Draft | `TlsServerConfig`, resolvers, ACME path, server invariants |
| [client.md](client.md) | Draft | `TlsClientConfig`, verifier selection, client auth, root-store fallback |
| [open-questions.md](open-questions.md) | live | The authoritative OQ tracker (all Phase 0 OQs resolved at entry) |

## ADRs

| ADR | Status | Decision |
|-----|--------|----------|
| [001](decisions/001-inherit-alknet-tls-design.md) | Accepted | Inherit the alknet TLS design as the baseline; deviations recorded as alktls ADRs |
| [002](decisions/002-tlserror-shape.md) | Accepted | `TlsError`: the ADR-088 six-variant shape from day one; config-construction scope boundary |
| [003](decisions/003-noq-replaces-quinn.md) | Accepted | The QUIC feature is `noq` (iroh's extracted fork), not `quinn`; iroh stays key-not-config |
| [004](decisions/004-accessor-surface.md) | Accepted | Complete accessors: `for_tcp_tls()` adopted; server borrows, client consumes |
| [005](decisions/005-config-types-move-into-alktls.md) | Accepted | Identity + credentials + fingerprint types move into alktls; auth layer stays out |
| [006](decisions/006-module-layout-and-tests.md) | Accepted | Eight-module layout; seed tests + integration invariant pins |

## Lifecycle

Docs move `Draft` → `Reviewed` when their open questions are resolved
and the architecture review reports zero critical issues; ADRs are
Accepted at write time and never revert (supersede instead).
`open-questions.md` is the authoritative tracker; the Phase 0 doc's
OQ statuses are the historical record.

## Phase status

- **Phase 0** (complete, 2026-09-10): `docs/research/phase-0.md` —
  extraction inventory, verified invariants, gaps, noq investigation,
  OQ-TLS-01..08.
- **Phase 1** (this directory): all Phase 0 OQs resolved at entry —
  six via ADR-001..006, two as documented behavior (OQ-TLS-02,
  OQ-TLS-06); review pass pending.
- **Phase 2** (next): decomposition into `tasks/` — the port guided by
  ADR-006's module map and seed tests.