edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d97118bb6a321eb7dec643e8a675711fe78dfbdd
chanora/dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md
T

18 KiB
Raw Blame History

Documentation Site & ASPICE Traceability System Design

Date: 2026-06-13 Status: Approved design for implementation Scope: Docusaurus doc site, git submodule separation, tag-based ASPICE traceability with custom validation plugin, Cloudflare Pages hosting with access control

1. Purpose

Replace the current flat markdown documentation tree with a browseable, searchable, access-controlled doc site that serves three audiences: developers, ASPICE assessors, and non-technical stakeholders. Introduce automated traceability enforcement that validates the ASPICE requirement chain on every build.

2. Current State

  • 65+ markdown files in docs/ with no sidebar, no search, no visual hierarchy
  • ASPICE traceability maintained in manual markdown tables (traceability-matrix.md)
  • Cross-references are backtick-quoted paths in prose, not clickable links
  • Link coverage report found 2 broken links + 5 broken path references
  • No CI enforcement of traceability integrity
  • No access control — docs only viewable via GitHub repo browsing or local clone

3. Design Decisions

Decision Choice Rationale
Repo structure Git submodule (docs/ → chanora-docs repo) Cleaner separation, access control, CI independence, separate versioning
Doc site generator Docusaurus Meta-maintained, full plugin API, built-in tags and versioning, active ecosystem
Traceability mechanism Tag-based + custom Docusaurus plugin Tags for browsing, plugin for automated chain validation and coverage reports
Hosting Cloudflare Pages Free tier, global CDN, auto-deploy from CI
Access control Cloudflare Access Free for up to 50 users, email-based auth, SSO support
Code path references in docs Remove from ASPICE docs, move to impl-mapping.md ASPICE traces requirement IDs, not file paths. Code paths are developer convenience
Provenance records Deferred Completed ASPICE-related plans archived in dev-docs/superpowers/plans/_archived/ for now

4. Repo Structure

4.1 Docs submodule (chanora-docs repo)

chanora-docs/
├── docusaurus.config.ts
├── sidebars.ts
├── package.json
├── package-lock.json
├── tsconfig.json
├── docs/
│   ├── index.md
│   ├── requirements/
│   │   ├── sysrs.md
│   │   ├── sysdes.md
│   │   └── srs.md
│   ├── architecture/
│   │   ├── sad.md
│   │   ├── sdd.md
│   │   ├── file-transfer-design.md
│   │   ├── file-transfer-research.md
│   │   ├── file-transfer-implementation-plan.md
│   │   └── desktop-ptt-architecture.md
│   ├── verification/
│   │   ├── verification-master-plan.md
│   │   ├── swe4-unit-verification-plan.md
│   │   ├── swe5-software-integration-verification-plan.md
│   │   ├── swe6-software-verification-plan.md
│   │   └── sys4-system-integration-verification-plan.md
│   ├── governance/
│   │   ├── document-index.md
│   │   ├── traceability-matrix.md
│   │   ├── product-decision-register.md
│   │   ├── baseline-approval-record.md
│   │   ├── baseline-candidate-validation-report.md
│   │   ├── document-review-report.md
│   │   ├── document-naming-convention.md
│   │   ├── decision-impact-assessment.md
│   │   ├── git-commit-message-convention.md
│   │   ├── repo-format-validation-report.md
│   │   ├── path-migration-map.md
│   │   └── maintainability-review-2026-06-08.md
│   ├── security/
│   │   ├── security-privacy-legal-guideline.md
│   │   ├── threat-model.md
│   │   ├── secure-storage-audit-report.md
│   │   ├── diagnostic-redaction-audit-report.md
│   │   ├── dependency-and-supply-chain-report.md
│   │   ├── license-inventory.md
│   │   └── flutter-license-inventory.md
│   ├── privacy/
│   │   └── privacy-policy.md
│   ├── legal/
│   │   └── trademark-and-attribution-review.md
│   ├── release/
│   │   ├── platform-release-policy.md
│   │   ├── release-readiness-go-nogo-record.md
│   │   └── dv-waiver-register.md
│   ├── references/
│   │   ├── aspice-swe2-swe3-integration-note.md
│   │   ├── external-references.md
│   │   ├── yatqa-en.md
│   │   ├── yatqa-de.md
│   │   ├── teaspeak-overview.md
│   │   └── respeak-overview.md
│   ├── ui-ux/
│   │   ├── material3-guideline.md
│   │   ├── material3-design-tokens.md
│   │   ├── material3-component-catalog.md
│   │   └── adaptive-layout-platform-guide.md
│   └── i18n/
│       └── localization-architecture.md
├── plugins/
│   └── traceability/
│       └── index.js
├── scripts/
│   ├── validate-traceability.mjs
│   └── add-requirement-tags.mjs
├── src/
│   ├── pages/index.tsx
│   └── css/custom.css
├── static/
│   └── img/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── wrangler.toml
└── README.md

4.2 Code repo local files

chanora/
├── docs/ → chanora-docs (submodule)
├── dev-docs/
│   ├── superpowers/
│   │   ├── specs/
│   │   │   ├── 2026-05-28-server-resolution-prefetch-design.md
│   │   │   ├── 2026-05-28-chanora-server-prefetch-crate-design.md
│   │   │   ├── 2026-05-29-state-sync-ui-settings-validation-design.md
│   │   │   ├── 2026-06-05-adaptive-3-panel-layout-design.md
│   │   │   ├── 2026-06-08-maintainability-continuation-design.md
│   │   │   ├── 2026-06-09-poke-without-message-design.md
│   │   │   └── 2026-06-13-documentation-site-design.md
│   │   └── plans/
│   │       ├── _archived/
│   │       │   ├── 2026-05-29-finish-dv-document-tree.md
│   │       │   ├── 2026-05-29-dv-evidence-pack.md
│   │       │   ├── 2026-05-29-swe2-swe3-baselines.md
│   │       │   └── 2026-05-29-state-sync-ui-settings-validation.md
│   │       ├── 2026-05-28-server-resolution-prefetch.md
│   │       ├── 2026-05-28-chanora-server-prefetch-crate.md
│   │       ├── 2026-06-06-chat-panel-switching.md
│   │       ├── 2026-06-08-core-internal-split.md
│   │       └── 2026-06-08-maintainability-continuation.md
│   ├── offline-knowledge/
│   │   ├── coverage-analysis.md
│   │   ├── doc-quality-analysis.md
│   │   ├── link-coverage-report.md
│   │   └── reviews/
│   ├── implementation-status-2026-05-28.md
│   ├── release/ios-build.md
│   └── impl-mapping.md
├── apps/, crates/, core/
├── AGENTS.md
└── README.md

5. Docusaurus Configuration

5.1 Site configuration (docusaurus.config.js)

module.exports = {
  title: 'Chanora Engineering Docs',
  tagline: 'ASPICE-compliant engineering documentation with automated traceability',
  url: 'https://docs.chanora.dev',
  baseUrl: '/',
  organizationName: 'chanoraapp',
  projectName: 'docs',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  i18n: { defaultLocale: 'en', locales: ['en'] },
  themes: ['@docusaurus/theme-classic'],
  plugins: [
    './plugins/traceability',
  ],
  themeConfig: {
    navbar: {
      title: 'Chanora Docs',
      items: [
        { type: 'doc', position: 'left', label: 'Requirements', docId: 'requirements/sysrs' },
        { type: 'doc', position: 'left', label: 'Architecture', docId: 'architecture/sad' },
        { type: 'doc', position: 'left', label: 'Verification', docId: 'verification/verification-master-plan' },
        { type: 'doc', position: 'left', label: 'Governance', docId: 'governance/document-index' },
        { type: 'doc', position: 'left', label: 'Security', docId: 'security/security-privacy-legal-guideline' },
        { type: 'doc', position: 'left', label: 'Release', docId: 'release/platform-release-policy' },
        { type: 'doc', position: 'left', label: 'References', docId: 'references/external-references' },
        { type: 'doc', position: 'left', label: 'UI/UX', docId: 'ui-ux/material3-guideline' },
        { type: 'tags' },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        { title: 'Docs', items: [
          { label: 'Requirements', to: '/docs/requirements/sysrs' },
          { label: 'Architecture', to: '/docs/architecture/sad' },
          { label: 'Verification', to: '/docs/verification/verification-master-plan' },
        ]},
        { title: 'Governance', items: [
          { label: 'Traceability Matrix', to: '/docs/governance/traceability-matrix' },
          { label: 'Decision Register', to: '/docs/governance/product-decision-register' },
          { label: 'Document Index', to: '/docs/governance/document-index' },
        ]},
      ],
    },
    prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula },
  },
};

5.2 Sidebar (sidebars.js)

module.exports = {
  requirements: [
    'requirements/sysrs',
    'requirements/sysdes',
    'requirements/srs',
  ],
  architecture: [
    'architecture/sad',
    'architecture/sdd',
    'architecture/file-transfer-design',
    'architecture/file-transfer-research',
    'architecture/file-transfer-implementation-plan',
    'architecture/desktop-ptt-architecture',
  ],
  verification: [
    {
      type: 'category',
      label: 'System Level',
      items: ['verification/sys4-system-integration-verification-plan'],
    },
    {
      type: 'category',
      label: 'Software Integration',
      items: ['verification/swe5-software-integration-verification-plan'],
    },
    {
      type: 'category',
      label: 'Unit Level',
      items: ['verification/swe4-unit-verification-plan'],
    },
    {
      type: 'category',
      label: 'Software Qualification',
      items: ['verification/swe6-software-verification-plan'],
    },
    'verification/verification-master-plan',
  ],
  governance: [
    'governance/document-index',
    'governance/traceability-matrix',
    'governance/product-decision-register',
    'governance/baseline-approval-record',
    'governance/baseline-candidate-validation-report',
    'governance/document-review-report',
    'governance/document-naming-convention',
    'governance/decision-impact-assessment',
    'governance/git-commit-message-convention',
    'governance/repo-format-validation-report',
    'governance/path-migration-map',
    'governance/maintainability-review-2026-06-08',
  ],
  security: [
    'security/security-privacy-legal-guideline',
    'security/threat-model',
    'security/secure-storage-audit-report',
    'security/diagnostic-redaction-audit-report',
    'security/dependency-and-supply-chain-report',
    'security/license-inventory',
    'security/flutter-license-inventory',
    'privacy/privacy-policy',
    'legal/trademark-and-attribution-review',
  ],
  release: [
    'release/platform-release-policy',
    'release/release-readiness-go-nogo-record',
    'release/dv-waiver-register',
  ],
  references: [
    'references/external-references',
    'references/aspice-swe2-swe3-integration-note',
    'references/yatqa-en',
    'references/yatqa-de',
    'references/teaspeak-overview',
    'references/respeak-overview',
  ],
  uiux: [
    'ui-ux/material3-guideline',
    'ui-ux/material3-design-tokens',
    'ui-ux/material3-component-catalog',
    'ui-ux/adaptive-layout-platform-guide',
    'i18n/localization-architecture',
  ],
};

6. Tag-Based Traceability

6.1 Front matter schema

Every document includes YAML front matter:

---
tags: [swe.2, architecture, SRS-003, SRS-008, SRS-016]
upstream: [srs, sysdes]      # Custom metadata for traceability plugin
downstream: [sdd, swe4, swe5] # Custom metadata for traceability plugin
lifecycle: SWE.2              # Custom metadata for traceability plugin
status: baseline              # Custom metadata for traceability plugin
---

The tags field is consumed by the Docusaurus tags system for browsing. The upstream, downstream, lifecycle, and status fields are custom metadata consumed by the traceability plugin for chain validation.

6.2 Tag categories

Tag pattern Purpose Example
swe.1 through swe.6, sys.4 ASPICE lifecycle stage Every doc gets at least one
sysrs, sysdes, srs, sad, sdd Document type Identifies the doc in the chain
requirements, architecture, verification, governance Section category For filtering
SysRS-233, SRS-045, SDD-MOD-009 Requirement/module IDs Traceability links
baseline, draft, candidate Document status Assessor visibility
dec-012, dec-020 Decision register refs Cross-ref to governance

6.3 Section defaults

Docusaurus uses front matter tags: per document. Section-level defaults are not needed since each document carries its own tags.

6.4 Verification page trace mappings

Verification plan Upstream traces Tags
SYS.4 System Integration SysDes, SysRS [sys.4, verification, SysDes-102, SysDes-103, ...]
SWE.5 Software Integration SAD (SWE.2) [swe.5, verification, sad-component-bridge, ...]
SWE.4 Unit Verification SDD (SWE.3) [swe.4, verification, SDD-MOD-001, ...]
SWE.6 Software Verification SRS [swe.6, verification, SRS-128, ...]

7. Custom Traceability Plugin

7.1 Location

plugins/traceability/index.js — Docusaurus plugin, ~100 lines JavaScript.

7.2 Behavior

On on_page_markdown event:

  • Scan each page for requirement ID patterns: SysRS-\d+, SysDes-\d+, SRS-\d+, SDD-MOD-\d+, DEC-\d+
  • Build an in-memory traceability graph: upstream ID → downstream document → verification plan

On on_post_build event:

  • Validate every requirement ID referenced downstream exists in its source document
  • Validate every upstream document ID has at least one downstream allocation
  • Flag orphaned references (IDs mentioned but never defined)
  • Verify bidirectional completeness

7.3 Outputs

  • traceability-coverage.json — machine-readable coverage report with chain completeness percentages
  • Console output with pass/fail summary
  • Traceability dashboard page with coverage table and broken chain details
  • Build failure (sys.exit(1)) on broken chains when strict: true

7.4 Standalone CI validator

scripts/validate-traceability.mjs — same validation logic, runnable without Docusaurus build:

python scripts/validate_traceability.py docs/

Exit code 0 = all chains valid. Exit code 1 = broken chains with details on stderr.

8. Hosting & Deployment

8.1 Architecture

chanora-docs repo → push to main → GitHub Actions
    → validate-traceability.mjs
    → npm run build
    → Cloudflare Pages (via Wrangler)
        → Cloudflare Access policy (email-based auth)

8.2 CI workflow

On pull request: build + validate only (no deploy). On push to main: build + validate + deploy to Cloudflare Pages.

8.3 Cloudflare Access policy

  • Free tier for up to 50 users
  • Email-based authentication with optional Google/GitHub SSO
  • One-time PIN for external assessors
  • Access rules: allow company emails, specific assessor emails; block all others

9. Migration Plan

9.1 Code path reference cleanup

SAD and SDD currently list file paths (crates/chanora_protocol/src/) in component tables. These references will be:

  • Replaced with component/module IDs only in the docs submodule
  • Preserved in dev-docs/impl-mapping.md in the code repo for developer convenience

9.2 File moves

From (code repo) To Action
docs/sysrs.md docs submodule Move + add front matter
docs/sysdes.md docs submodule Move + add front matter
docs/srs.md docs submodule Move + add front matter
docs/requirements/* docs submodule Move (path records)
docs/architecture/* docs submodule Move + cleanup code paths
docs/verification/* docs submodule Move + add front matter
docs/governance/* docs submodule Move + add front matter
docs/security/* docs submodule Move + add front matter
docs/privacy/* docs submodule Move
docs/legal/* docs submodule Move
docs/release/policy+go-nogo+waiver docs submodule Move
docs/references/* docs submodule Move
docs/ui-ux/* docs submodule Move
docs/i18n/* docs submodule Move
docs/material3-guideline.md docs submodule Move
docs/offline-knowledge/external/* docs submodule references/ (flattened) Move + rename
docs/superpowers/* dev-docs/superpowers/ Move
docs/offline-knowledge/ (remaining) dev-docs/offline-knowledge/ Move
docs/implementation-status-* dev-docs/ Move
docs/release/ios-build.md dev-docs/release/ Move

9.3 Cross-reference updates

All backtick path references (docs/srs.md) should become markdown links ([SRS](../srs.md) or [SRS](srs.md)) for both GitHub and Docusaurus rendering.

9.4 Post-migration

  • Remove docs/ contents from code repo
  • Add chanora-docs as git submodule at docs/
  • Create dev-docs/ directory with local-only files
  • Update README references to new paths
  • Write AGENTS.md with new conventions
  • Update opencode.json or .opencode/ references

10. AGENTS.md

An AGENTS.md file will be written at the code repo root documenting:

  • The two-repo model (docs/ as submodule, dev-docs/ as local)
  • What content goes where
  • ASPICE traceability chain and rules
  • Code architecture overview
  • Verification commands
  • Agent working conventions (no edits in docs/ without submodule awareness)

11. Deferred Items

Item Reason When
Document provenance records Convert completed ASPICE plans into provenance evidence Follow-up task
Custom Docusaurus traceability plugin Core feature, built during implementation Phase 1
Cloudflare Pages + Access setup Requires account creation, domain config During deployment
impl-mapping.md creation Extract code paths from SAD/SDD during migration During migration
Reference in New Issue View Git Blame Copy Permalink