Hub documentation is intentionally slim. Cross-cutting architectural decisions live in the LearnStack core repository and Hub docs link to them rather than restating them. What lives here is what only the Hub can own:
- The Hub roadmap — the plan for this repository, one document per packet
- Hub-internal architecture (repository layout, module topology, the contract pointers)
- Hub module deep-dives (Hub-only implementation details)
- Hub-internal ADRs (decisions that affect only the Hub)
- Hub operational runbooks
- Hub-specific glossary terms
| Directory | Purpose | Numbering |
|---|---|---|
roadmap/ |
The authoritative Hub plan. One document per packet (P02c-0 … P02c-7) plus the post-02c billing and marketplace tracks. Not a mirror of a LearnStack file — LearnStack's phase-02c covers only its own side of the boundary and links here for the rest. |
pNNc-N-topic.md |
architecture/ |
Hub-internal architecture — repository layout, module topology, cross-cutting foundation, entitlement projection — plus the contract pointers to LearnStack core | flat, unnumbered |
decisions/ |
Hub-internal ADRs (Hub-only decisions; HUB-NNNN series so they never collide with LearnStack ADR numbers) |
HUB-NNNN-topic.md |
operations/ |
Hub operational runbooks (deployment, incident response, cert rotation) | unnumbered |
modules/ |
Per-Hub-module deep dives + audit-coverage matrices | per-module files |
glossary.md |
Hub-specific terms (Plan, HubSubscription, Entitlement, Hub Operator) |
single file |
Every roadmap packet document carries the same six sections as a LearnStack phase document: Goal, Scope, Deliverables, Completion Criteria, Risks, Phase Exit Decision.
Hub docs cite these by absolute URL (https://github.com/HodeTech/LearnStack/blob/main/docs/...), per Documentation Standards § Layout. Relative paths do not cross a repository boundary on github.com and depend on a sibling checkout being present and identically capitalised.
- ADR-0019 LearnStack Hub — why the Hub is a separate repository
- ADR-0034 Hub Contract Surface Invariant — the two invariants that replaced the "closed at four endpoints" rule, and the authoritative endpoint table
- ADR-0035 Demand-Gated Infrastructure — why the Hub integration waits on a written trigger
- ADR-0033 Audit Durability Model — MUST-class audit as durable intent (supersedes ADR-0016)
- ADR-0020 Triple Deployment + Hybrid License
- ADR-0021 Feature-Based Entitlement
- ADR-0022 Custom Domain + TLS (Amendment 1; its cert-delivery step is superseded by ADR-0034)
- ADR-0004 Authentication Strategy (Amendment 1 —
learnstack-hubrealm) - Architecture 24 LearnStack Hub — the deep dive
- Standards 20 Infrastructure Stack
- Standards 21 Architecture Tests Catalogue
- Phase 02c — LearnStack side
Hub follows LearnStack's Standards corpus by reference. Hub does not maintain its own standards. If a Hub-internal-only rule emerges (for example a Stripe webhook idempotency strategy), it lands as a Hub-internal ADR (HUB-NNNN), not as a standards file.
This repository maintains its own skill catalogue at .claude/skills/ — 18 skills, git-tracked through an un-ignore rule in .gitignore. Agents running from the Hub repository root load them from there, not from the sibling LearnStack repo.
The catalogue is Hub-tailored: the add-hub-* workflows encode Hub's deltas from LearnStack core — no Row Level Security, OperatorId rather than UserId, a six-step MediatR pipeline rather than eight, the hub schema, the learnstack_hub database. Entry-point selection is unchanged: implement-task for substantive work, start-task for scoping, standards-check then code-review for review.