ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
website-dev
TenantAtlas/specs/410-public-docs-ia/data-model.md
ahmido af5fa30341 410: add public docs information architecture (#412) 
Implements website feature branch `410-public-docs-ia`.

Target branch: `website-dev`.

Validation:
- `corepack pnpm --filter @tenantatlas/website build`
- Playwright smoke coverage for public routes and docs interactions
- Static claim scans for `apps/website/src`, `apps/website/public`, and `apps/website/dist`

Follow-up integration path after merge:

`website-dev` -> `dev`.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #412
2026-05-31 21:11:07 +00:00

5.1 KiB
Raw Permalink Blame History

Data Model: Public Docs & Knowledge Base IA

This feature has no persisted runtime data model. The entities below are static website content structures used to render the public docs IA, its navigation, and its public route contract. They must remain content-only unless a later spec introduces authenticated docs, CMS behavior, or search/indexing changes beyond the current Starlight build.

Docs Home Page

Represents: The localized landing page for the public knowledge base.

Fields:

  • locale: de or en
  • slug: /docs/ or /en/docs/
  • pageTitle: localized metadata title
  • metaDescription: localized metadata description
  • heroTitle: main H1
  • heroSubtitle: primary supporting paragraph
  • supportingLine: audience and evaluation-readiness framing
  • primaryStartLink: main route into the docs topic tree
  • categoryCards: ordered topic-card list
  • relatedPublicLinks: optional real links to trust, evaluation, platform, review-packs, or contact

Validation rules:

  • The page must expose all twelve required topic categories.
  • All links must resolve to real public routes.
  • Metadata and body copy must avoid unsupported compliance, provider, hosting, or automation claims.

Docs Topic Page

Represents: One localized docs topic page under the /docs route family.

Fields:

  • locale: de or en
  • slug: one of the required topic slugs
  • title: localized H1
  • metaTitle: localized metadata title
  • metaDescription: localized metadata description
  • intro: short purpose paragraph
  • whatThisPageCovers: short scope block
  • sections: ordered 3-6 content sections
  • relatedLinks: real public links to other docs pages or adjacent public pages
  • claimBoundaryNotes: optional bounded-scope wording where completeness would be misleading

Slug enum:

  • getting-started
  • microsoft-365-provider
  • permissions-data-access
  • data-processing-trust
  • policy-evidence
  • drift-detection
  • backups-versioning-recovery
  • findings-exceptions-accepted-risk
  • review-packs-decisions
  • evaluation-pilot
  • known-limitations
  • faq

Validation rules:

  • Each topic page must include title, intro, what this page covers, 3-6 sections, and related links.
  • Topic pages must use public-facing language rather than internal architecture jargon.
  • Topic pages must not invent a complete Microsoft permission matrix, legal downloads, or unsupported feature claims.

Category Card

Represents: One topic entry on the docs home page.

Fields:

  • slug: one of the docs topic slugs
  • label: localized visible label
  • summary: short public description
  • href: real localized docs route

Validation rules:

  • Card order must match the approved IA order in the plan/spec.
  • Card text must describe user questions, not internal modules.

Sidebar Section

Represents: One explicit grouping of docs topic links in the Starlight sidebar.

Fields:

  • key: stable config key
  • label: localized visible label
  • items: ordered topic links

Validation rules:

  • Sidebar order must stay explicit rather than implicit from directory autogeneration.
  • Grouping may improve readability, but it must not hide or rename the required topic pages.

Related Public Link

Represents: A public handoff from docs to another verified public route.

Fields:

  • label: visible link label
  • href: real localized route
  • placement: docs-home, docs-topic, homepage, platform, trust, evaluation, review-packs, use-case, nav, or footer

Validation rules:

  • Links must point only to routes that exist in the current site.
  • No placeholder anchors or fake downloads are allowed.

Legacy Docs Alias

Represents: A current public starter-docs route that must continue to resolve after the new docs IA ships.

Fields:

  • from: current public URL
  • to: new public docs URL
  • locale: de or en
  • reason: continuity rationale

Required mappings:

  • /welcome-to-docs/ -> /docs/
  • /guides/intro/ -> /docs/getting-started/
  • /guides/getting-started/ -> /docs/getting-started/
  • /guides/first-project-checklist/ -> /docs/evaluation-pilot/
  • /platform/evidence-review/ -> /docs/policy-evidence/
  • /en/welcome-to-docs/ -> /en/docs/
  • /en/guides/intro/ -> /en/docs/getting-started/
  • /en/guides/getting-started/ -> /en/docs/getting-started/
  • /en/guides/first-project-checklist/ -> /en/docs/evaluation-pilot/
  • /en/platform/evidence-review/ -> /en/docs/policy-evidence/

Validation rules:

  • Alias handling must preserve user-facing continuity for any currently exposed docs route.
  • The project must not keep both old and new docs pages as permanent parallel truth.

Footer / Navigation Docs Link

Represents: The global public-site docs entry point exposed through existing navigation and footer structures.

Fields:

  • label: Docs or localized equivalent already used by the site
  • href: /docs/ or /en/docs/
  • surface: nav or footer

Validation rules:

  • The docs href must be localized via the existing locale helper path.
  • Any previous /welcome-to-docs/ references in navigation or footer must be migrated.