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