alkgit/docs/architecture/overview.md

status, last_updated

status	last_updated
draft	2026-09-21

Overview: alkgit

Purpose

alkgit is a self-hosted git server: repository storage, the git smart protocol served over http and ssh interfaces, and the alkgitd binary that assembles it all. It exists to provide a small, security-first git platform whose exposure model inverts the mainstream pattern (visible-surface = authorized-surface, authenticated-by-default, no plaintext secrets, no plugin execution). See docs/research/vision.md for the full WHY.

The one-line architecture

Storage + ACL + protocol adapters. alkgit-core owns repository storage and access-rule types; alkgit-transport owns the git protocol state machines; alkgit-http and alkgit-ssh are thin front doors that authenticate, resolve the repo, and hand a session to the transport; alkgitd assembles everything with config, TLS/ACME, and the vault.

Crate map

Crate	Owns	Depends on	Never depends on
alkgit-core	repo registry/storage roots, odb wrappers, ref store, pack generate/ingest, fsck, ACL input types	gix crates, alkcall (ACL types only)	any front-door crate
alkgit-transport	pkt-line sessions, V2 advertisement/state machine, ls-refs, fetch, receive-pack	alkgit-core, alkcall, gix-packetline	alkhttp, alkgit-ssh
alkgit-http	smart-http endpoints over alkhttp	transport, core, alkhttp	alkgit-ssh, alkgitd
alkgit-ssh	git-command dispatch for exec requests over alkcall channels	transport, core, alkcall	alkhttp, alkgitd
alkgitd	binary: config, assembly, TLS/ACME, listeners, vault wiring	everything	—

Dependency rules (ADR-001, ADR-002):

1. alkgit-core + alkgit-transport are front-door-blind: they consume (identity, repo id, duplex stream, limits) and depend on alkcall types only. No http types, no ssh channel types below the stream.
2. alkgit-http and alkgit-ssh never depend on each other.
3. alkgitd is the only crate allowed to know the whole graph.
4. A downstream application (gitea-like) embeds core + transport and brings its own front doors; the admin API is a set of alkcall ops it may use or replace.

Security invariants (spec-level, all components honor)

These are the load-bearing rules from docs/research/vision.md and docs/research/alk-stack.md; each component doc references them where concrete:

1. Authenticated by default — anonymous fetch exists only on explicitly-public repos; push is always authenticated.
2. Visible-surface = authorized-surface — via alkcall ACL; ops with Visibility::Internal are never wire-callable; admin ops ride an admin surface, never the git traffic surface.
3. ACL before advertisement — access is checked before any ref line or capability line is emitted (ref names leak repo existence) (ADR-007).
4. Registry-resolved repo identity — wire-supplied repo names are IDs resolved to server-configured storage roots; never used as paths (ADR-008).
5. No secret material on the wire or at rest outside alkvault — metadata holds vault references only; outbound credentials flow through alkcall Capabilities (alkcall ADR-010), and no handler reads credentials from env or files (the no-env-vars invariant).
6. No shelling out to git — serving path is pure Rust on gix primitives (GPL hygiene + no process-injection surface).
7. Bounded resources — every session carries wall-clock, size, and round limits (ADR-009); unbounded loops/buffers are bugs.
8. Honest capability advertisement — the protocol advertises exactly what we serve (ADR-003).

Interfaces (the boundary shape)

The core boundary, from POC-1 (docs/research/poc-1-findings.md, follow-up 4) and the "ALPN as a service" rule in docs/research/vision.md:

• Transport input: one session = (peer identity from alkcall AuthContext, repo id resolved against the registry, a duplex byte stream, session limits). For the stateless http door this becomes (identity, repo, request-reader, response-writer, limits) — the same state machines, a different substrate (ADR-005).
• Storage input: the transport asks core for (a) ref advertisement data, (b) pack generation for a want/have set, (c) pack ingestion + ref transactions for receive-pack. Storage never sees pkt-lines.

What is already validated (POC-backed)

• pkt-line over alkcall BiStream end-to-end (POC-1).
• Pack generation pipeline streaming with O(counts) memory (POC-2).
• Smart-http streaming both ways through alkhttp custom routes (POC-3). The full V2 fetch path against real git 2.43 is proven; receive-pack is designed but not yet exercised (OQ-04 tracks the POC/validation gap).

Design Decisions

ADR	Decision	Summary
001	Crate decomposition	5 crates: core, transport, http, ssh, alkgitd
002	Front-door-blind core	Session boundary = (identity, repo, stream, limits)
003	V2-first protocol	V2-only fetch on both doors; honest advertisement; multi-round negotiation sequenced (OQ-02); push surface OQ-04
004	Pack pipeline	gitoxide data::output generation, streaming-input ingestion
005	Substrate types	Duplex + stateless session APIs over one state machine
006	HTTP adapter composition	Router factory in alkgit-http (proposed, OQ-01)
007	ACL first	No ref/capability line before ACL passes
008	Repo identity	Wire names are registry IDs
009	Budgets	Every session carries limits

Open Questions

Key cross-cutting questions tracked in open-questions.md:

• OQ-01: http adapter composability (where the smart-http routes live for downstream embedding) — affects http.md and ADR-006.
• OQ-04: receive-pack (push) validation gap (high — the always-authenticated half of the wire surface).
• OQ-08: identity sources per front door (how http and ssh authenticate peers in v1).
• OQ-06: metadata store backing for the registry (config-file vs embedded store vs alkcall-hosted).