Engineering decisions

49 architecture decisions are recorded. These eight explain the repository best.

  1. ADR-005
    Build One Immutable Documentation Platform

    One immutable platform object is the backbone every documentation tool reads from.

  2. ADR-019
    Introduce a Documentation SDK

    A single high-level SDK turned internal packages into a product others can adopt.

  3. ADR-036
    Adopt a Vertical Slice Strategy

    Products are built end to end as vertical slices instead of layer by layer.

  4. ADR-037
    Prefer Delayed Extraction Across Vertical Slices

    Shared code is extracted only after a second product proves the need.

  5. ADR-038
    Prefer Capability Extraction Over Framework Extraction

    What gets shared are capabilities such as storage and search, never framework code.

  6. ADR-044
    Introduce Runtime Independence Validation

    Runtime independence is tested with real services, not assumed.

  7. ADR-048
    Introduce Framework-Neutral Design Tokens

    Visual consistency comes from framework-neutral tokens, not a shared component library.

  8. ADR-049
    Introduce a Derived Repository Atlas

    This Atlas derives its inventories from the repository instead of maintaining copies.

All decisions, by phase
IDTitleDecidedStatus
Foundation and documentation ecosystem
ADR-001Centralize Documentation Infrastructure in a Framework-Agnostic PackagePlace reusable documentation parsing, validation, and models in one stable workspace package.Milestones: M1.2accepted
ADR-002Keep the Document Registry as an InventoryDiscover, collect, and expose parsed documents without interpreting their relationships or presentation.Milestones: M1.3accepted
ADR-003Resolve Only Declared Metadata RelationshipsDerive forward references and backlinks from canonical metadata without changing the Document Registry or inspecting Markdown content.Milestones: M1.4accepted
ADR-004Use Deterministic Search over the Document RegistryBuild framework-agnostic field search from canonical registry entries with explicit ranking and stable ordering.Milestones: M1.5accepted
ADR-005Build One Immutable Documentation Platform FeaturedCentralize lifecycle orchestration while preserving the responsibilities of Registry, Reference Resolution, and Search.Milestones: M1.6accepted
ADR-006Make the Knowledge Hub a Documentation Platform ConsumerRemove application-owned documentation infrastructure and keep the Knowledge Hub focused on presentation.Milestones: M1.7accepted
ADR-007Expose Documentation through a Read-Only Repository CLIAdd an independent terminal application that consumes the Documentation Platform without introducing documentation logic.Milestones: M2accepted
ADR-008Version Structured Repository CLI OutputExpose Documentation Platform results as a stable, versioned JSON contract while preserving text as the default.Milestones: M2.1accepted
ADR-009Separate Documentation Quality Linting from Structural ValidationEvaluate repository quality conventions in a reusable linter that consumes the Documentation Platform independently from the CLI.Milestones: M2.2accepted
ADR-010Export Documentation Platform Snapshots as Static JSONGenerate deterministic offline artifacts in a separate read-only application that consumes one Documentation Platform.Milestones: M2.3accepted
ADR-011Stabilize Documentation Package Entry PointsDefine versioned root package APIs while keeping implementation modules and delivery schemas independently evolvable.Milestones: M2.4accepted
ADR-012Consume Stable Documentation APIs in VS CodeAdd a read-only editor application that delegates documentation knowledge and quality evaluation to the stable package roots.Milestones: M2.5accepted
ADR-013Ground AI Services in the Documentation PlatformAdd a provider-independent interpretation layer whose prompts and normalized responses remain grounded in canonical Platform data.Milestones: M2.6accepted
ADR-014Keep Documentation Recommendations DeterministicRank repository-implied document relevance with explicit reproducible rules while leaving explanation to the AI service layer.Milestones: M2.7accepted
ADR-015Centralize Documentation ConfigurationDefine one strict repository-owned configuration contract shared by every documentation consumer.Milestones: M2.8accepted
ADR-016Resolve Documentation Configuration OnceShare one immutable, source-aware policy object across every documentation package and application.Milestones: M2.9accepted
ADR-017Prepare Documentation Packages for External DistributionTreat reusable documentation packages as validated release units while keeping applications private.Milestones: M3.0accepted
ADR-018Validate Documentation Packages Through an External ConsumerProtect public package contracts with a tracked third-party-style integration fixture.Milestones: M3.1accepted
ADR-019Introduce a Documentation SDK FeaturedProvide one recommended façade for common external workflows while preserving specialized packages.Milestones: M3.2accepted
ADR-020Manage Documentation Package VersionsUse independently versioned Changesets plans for documentation packages and their internal dependency graph.Milestones: M3.3accepted
ADR-021Introduce Documentation Extension ContractsExpose a small set of typed integration contracts without introducing runtime plugin infrastructure.Milestones: M3.4accepted
ADR-022Dogfood the Documentation SDKMake the Knowledge Hub an SDK-only first-party consumer and protect that public package boundary.Milestones: M4.0accepted
ADR-023Standardize Repository BootstrapProvide a conservative SDK helper that creates a valid documentation environment without creating or overwriting repositories.Milestones: M5.0accepted
ADR-024Define Documentation CI ContractExpose deterministic documentation validation orchestration without coupling the ecosystem to an automation provider.Milestones: M5.1accepted
ADR-025Introduce Documentation DoctorSeparate deterministic remediation guidance from validation through a read-only SDK diagnostic engine.Milestones: M5.2accepted
ADR-026Introduce Repository Health AssessmentProvide deterministic, informational maintainability metrics over an existing Documentation Platform without creating validation or grading semantics.Milestones: M5.3accepted
ADR-027Standardize Package Release WorkflowCoordinate versioning, existing verification, deterministic artifacts, and release review without coupling preparation to publication or a registry.Milestones: M6.0accepted
ADR-028Add npm Publication ReadinessAdapt registry-independent release artifacts to safe, explicit, read-only npm readiness without exposing publication through the SDK.Milestones: M6.1accepted
ADR-029Build the Documentation Website on the Public SDKMake the official product documentation a first-party reference consumer of the stable documentation SDK.Milestones: M6.2accepted
ADR-030Derive the Documentation Graph as a Deterministic VisualizationVisualize existing Registry and Reference Resolver information without creating a second graph data source.Milestones: M6.3accepted
ADR-031Introduce Documentation Compatibility AnalysisAssess explicit platform targets through deterministic read-only rules without coupling compatibility to migration execution.Milestones: M6.4accepted
ADR-032Documentation Upgrade PlanningKeep upgrade planning deterministic and read-only by deriving every step from an existing compatibility report.Milestones: M6.5accepted
ADR-033Documentation Upgrade VerificationCompare preserved upgrade plans with current compatibility and explicit evidence through a deterministic, read-only verification model.Milestones: M6.6accepted
ADR-034Adopt a Release-Candidate Acceptance ProcessRequire supported-runtime, public-contract, external-consumer, performance, security, accessibility, and release-rehearsal evidence before release.Milestones: M7.0accepted
ADR-035Define Browser, Platform, and CLI Acceptance BoundariesRequire runtime browser and Linux evidence while keeping Windows, warnings, CLI distribution, and live publication claims explicit.Milestones: M7.0, M7.1accepted
Product vertical slices
ADR-036Adopt a Vertical Slice Strategy FeaturedValidate product architecture with one complete notes feature path.Milestones: M8.0accepted
ADR-037Prefer Delayed Extraction Across Vertical Slices FeaturedKeep Fieldnotes and Fieldmarks independent until reuse is proven.Milestones: M8.1accepted
ADR-038Prefer Capability Extraction Over Framework Extraction FeaturedPromote proven mechanics while preserving independent product slices.Milestones: M8.2accepted
ADR-039Preserve Domain Ownership Across Shared CapabilitiesKeep Boardflow ordering and movement rules local while reusing bounded mechanics.Milestones: M8.3accepted
ADR-040Introduce Explicit Product Integration ContractsExchange stable product references without sharing product behavior or persistence.Milestones: M8.4accepted
Framework and runtime breadth
ADR-041Prefer Framework-Neutral CapabilitiesKeep shared product mechanics independent of React, Next.js, Vue, and Nuxt.Milestones: M9.0accepted
ADR-042Add a SvelteKit Vertical SliceValidate shared capability boundaries with an independently owned SvelteKit product.Milestones: M9.1accepted
ADR-043Introduce a Content-Oriented Framework SliceUse Astro for a statically generated knowledge garden while preserving package boundaries.Milestones: M9.2accepted
ADR-044Introduce Runtime Independence Validation FeaturedValidate a Bun-native service while keeping application and package boundaries independent of its runtime.Milestones: M9.3accepted
ADR-045Introduce Deno Runtime ValidationValidate explicit permissions and Deno-native tooling through an isolated event store.Milestones: M9.4accepted
ADR-046Introduce Python Service ValidationValidate a separate language ecosystem through an isolated FastAPI inventory service.Milestones: M9.5accepted
ADR-047Introduce .NET Runtime ValidationValidate the .NET ecosystem through an isolated ASP.NET Core diagnostics service.Milestones: M9.6accepted
ADR-048Introduce Framework-Neutral Design Tokens FeaturedShare visual foundations as immutable data and CSS custom properties without sharing components.Milestones: M10.0accepted
ADR-049Introduce a Derived Repository Atlas FeaturedOrient public visitors through a bilingual presentation consumer whose inventories are derived from repository sources rather than maintained by hand.Milestones: M10.1accepted