alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash 8f73da5d12 docs(architecture): phase 1 bootstrap — specs, 9 ADRs, OQ tracker

Architecture documentation structure per sdd_process phase 1:

- README index (doc table, ADR table, lifecycle), overview with crate
  map, dependency rules, and security invariants
- Component specs: storage, transport, http, ssh, alkgitd (all draft)
- ADRs 001-009: crate decomposition, front-door-blind core, V2-first
  protocol, pack pipeline (data::output generation / data::input
  ingestion), session substrate types, http adapter composition
  (proposed, OQ-01), ACL-before-advertisement, registry-resolved repo
  identity, bounded-resources budgets
- open-questions.md: OQ-01..08 with two deferred(scope), one
  deferred(unclear), door-type definitions, blocker tracker tasks in
  tasks/architecture/
- v1 ssh-door decision recorded: russh terminates wire SSH in alkgitd;
  alkcall channels stay the internal substrate (OQ-03 partially
  resolved)

Two review rounds (fresh-context subagent): 4 critical + 17 warnings
fixed in round one; zero critical + 4 warnings + 5 suggestions fixed in
round two. All ADR/OQ cross-references verified resolving.

2026-09-21 03:55:33 +00:00

3.5 KiB

Raw Blame History

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-01 (http adapter home / composability, blocks ADR-006 finalization), 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

3.5 KiB Raw Blame History