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.
66 lines
3.6 KiB
Markdown
66 lines
3.6 KiB
Markdown
---
|
|
status: draft
|
|
last_updated: 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/](../research/README.md); 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](overview.md) | Cross-cutting: crate map, dependency rules, security invariants | draft |
|
|
| [storage.md](storage.md) | `alkgit-core`: registry, refs, odb, pack generate/ingest, ACL types | draft |
|
|
| [transport.md](transport.md) | `alkgit-transport`: pkt-line sessions, V2 state machine, upload/receive-pack | draft |
|
|
| [http.md](http.md) | `alkgit-http`: smart-http adapter over alkhttp | draft |
|
|
| [ssh.md](ssh.md) | `alkgit-ssh`: git-command dispatch (wire SSH terminated by russh in alkgitd) | draft |
|
|
| [alkgitd.md](alkgitd.md) | `alkgitd`: binary assembly, config, TLS/ACME, serving loops | draft |
|
|
| [open-questions.md](open-questions.md) | Centralized OQ tracker | — |
|
|
|
|
## ADRs
|
|
|
|
| ADR | Decision | Status |
|
|
|---|---|---|
|
|
| [001](decisions/001-crate-decomposition.md) | Workspace crate decomposition (5 crates) | Accepted |
|
|
| [002](decisions/002-front-door-blind-core.md) | Front-door-blind core: session boundary (identity, repo, stream, limits) | Accepted |
|
|
| [003](decisions/003-protocol-v2-first.md) | Protocol V2-first with honest capability advertisement | Accepted |
|
|
| [004](decisions/004-pack-pipeline.md) | Pack generation/ingestion pipeline (gitoxide `data::output`) | Accepted |
|
|
| [005](decisions/005-session-substrate-types.md) | Session substrate types (duplex + stateless APIs, request reader) | Accepted |
|
|
| [006](decisions/006-http-adapter-composition.md) | HTTP adapter composition (alkgit-owned router factory) | Proposed |
|
|
| [007](decisions/007-acl-before-advertisement.md) | ACL runs before any advertisement/ref line | Accepted |
|
|
| [008](decisions/008-registry-resolved-repo-identity.md) | Wire repo names are registry IDs, never paths | Accepted |
|
|
| [009](decisions/009-bounded-resources-budget.md) | 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](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 | |