glm-5.3-flash
74029207e6
New open question capturing the doors-as-family-infrastructure direction: alkssh (planned) becomes the ssh door for git, git is a payload service exposed by downstream doors (alkhttp, alkssh, alknet), and the crate set may slim to protocol crates + http adapter (kept in alkgit, Slim-A, or promoted to an alkhttp git feature, Slim-B). OQ-09 carries the three sub-decisions (alkgit-ssh deletion vs temporary russh scaffolding; http adapter home; alkgitd consumption path) and cross-references ADR-006 (now flagged as possibly superseded before finalization) and OQ-01. Deferred summary table updated.
3.6 KiB
status, last_updated
| status | last_updated |
|---|---|
| draft | 2026-09-21 |
alkgit Architecture
Phase 1 (SDD) output for alkgit — the self-hosted, single-binary git server built on the alk stack (alkcall, alkhttp, alktls, alkvault) and gitoxide. Phase 0 research lives in docs/research/; every design claim here traces to a POC finding or research doc, or is flagged as an open question.
Current State
Phase 1 is starting. All architecture documents below are draft
(ADR-006 additionally carries a Proposed ADR status pending OQ-01).
POC-1/2/3 validated the git protocol half end-to-end against real git 2.43;
the remaining design work is shape work (adapter composability, metadata/
registry backing, admin surface, receive-pack).
Architecture Documents
| Doc | Area | Status |
|---|---|---|
| overview.md | Cross-cutting: crate map, dependency rules, security invariants | draft |
| storage.md | alkgit-core: registry, refs, odb, pack generate/ingest, ACL types |
draft |
| transport.md | alkgit-transport: pkt-line sessions, V2 state machine, upload/receive-pack |
draft |
| http.md | alkgit-http: smart-http adapter over alkhttp |
draft |
| ssh.md | alkgit-ssh: git-command dispatch (wire SSH terminated by russh in alkgitd) |
draft |
| alkgitd.md | alkgitd: binary assembly, config, TLS/ACME, serving loops |
draft |
| open-questions.md | Centralized OQ tracker | — |
ADRs
| ADR | Decision | Status |
|---|---|---|
| 001 | Workspace crate decomposition (5 crates) | Accepted |
| 002 | Front-door-blind core: session boundary (identity, repo, stream, limits) | Accepted |
| 003 | Protocol V2-first with honest capability advertisement | Accepted |
| 004 | Pack generation/ingestion pipeline (gitoxide data::output) |
Accepted |
| 005 | Session substrate types (duplex + stateless APIs, request reader) | Accepted |
| 006 | HTTP adapter composition (alkgit-owned router factory) | Proposed |
| 007 | ACL runs before any advertisement/ref line | Accepted |
| 008 | Wire repo names are registry IDs, never paths | Accepted |
| 009 | Bounded-resources budget model (limits on every session) | Accepted |
Note: ADR-001's crate table and ssh.md record the v1 ssh-door decision (russh terminates wire SSH in alkgitd; OQ-03 covers embedder variants).
Open Questions
All unresolved questions are tracked in open-questions.md with stable OQ-IDs, priorities, and cross-references. Highest-priority opens: OQ-09 (slim-crate model: doors as family infrastructure — may supersede ADR-006/001 shape), OQ-04 (receive-pack validation), OQ-06 (metadata store backing), OQ-08 (identity sources per front door).
Document Lifecycle
| Status | Meaning | Transitions |
|---|---|---|
draft |
Under active development; may change significantly | → reviewed when its OQs are resolved |
reviewed |
Architecture final; implementation may begin; changes need review | → stable when implementation verified |
stable |
Locked; changes require review, may warrant an ADR | → deprecated when superseded |
deprecated |
Superseded; kept for reference | Removed when no longer referenced |