Skip to Content
LYNKORIADocs

ADR 019: Documentation structure

  • Status: Accepted
  • Owner: Eng lead
  • Date: 2026-11-13

Context

Root docs/ mixed integrator guides, platform internals (docs/platform/), dated reviews and implementation trackers. Status lived in several overlapping pages (implementation-progress.md, platform/review.md, testing-completion-criteria.md, platform-status.md), so completed and pending work drifted apart.

Decision

  • Integrator guides stay at the top level of docs/ with unchanged URLs. SDK READMEs, Swift/Kotlin comments and error messages link to them.
  • Platform documentation is split into top-level sections, each a sidebar tab on the site: architecture/, security/, deployment/, operations/, decisions/, implementation/ and reviews/.
  • Each folder's landing page is README.md (GitHub shows it; apps/docs/lib/source.ts maps it to the folder URL).
  • implementation/ is the single tracker: one findings table with IDs and statuses in its README, plus completed.md, remaining-tasks.md, blockers.md and changelog.md. Reviews are dated and immutable once superseded; their still-open items move into the tracker rather than accumulating in review files.
  • platform-status.md remains the integrator-facing support matrix and must agree with the tracker.

Consequences

/docs/platform/* URLs moved to the new sections (/docs/deployment, /docs/architecture, …). Internal links were rewritten and are checked by apps/docs/test/content.test.mjs and the export link check.

On this page