ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
94cff6ca03
TenantAtlas/specs/406-provider-policy-domain-public-taxonomy/research.md
ahmido 09dc9988cb 406: Provider & Policy Domain Public Taxonomy (#401) 
## Summary
- add the 406 feature specification for a public provider and policy-domain taxonomy surface
- include plan, research, data model, quickstart, checklist, and public route contract artifacts
- update agent context with the 406 website technology notes

## Notes
- this PR is spec and planning work only
- no runtime website implementation is included yet

## Validation
- reviewed pending git scope before commit
- verified `Agents.md` has no editor diagnostics

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #401
2026-05-26 12:54:23 +00:00

6.3 KiB
Raw Blame History

Research: Provider & Policy Domain Public Taxonomy

Decision: Use /platform/domains and /en/platform/domains

Rationale: The existing public website already has /platform and /en/platform routes, uses Astro file-based routing, and contains nested documentation routes. A nested platform taxonomy route keeps the content connected to product positioning without cluttering the top-level IA.

Alternatives considered:

  • /policy-domains: clear but less connected to the platform page and current IA.
  • /domains: short but too generic for public SEO and buyer context.
  • Inline-only platform section: lower route overhead but weaker discoverability and harder metadata/smoke coverage.

Decision: Reuse the existing localized page-component pattern

Rationale: Current public pages use thin route files that pass locale into page components, for example /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/pages/platform.astro and /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/pages/en/platform.astro. A DomainTaxonomyPage.astro component can follow the same pattern for German default and English routes.

Alternatives considered:

  • MDX content route: useful for docs, but less aligned with current marketing pages and CTA/navigation patterns.
  • Inline route-only markup: works, but duplicates localization and layout structure across German and English routes.
  • CMS/content collection: out of scope and unnecessary for one bounded page.

Decision: Keep taxonomy data in existing website copy data

Rationale: The website already centralizes public copy in /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/data_files/site-copy.ts. Adding localized taxonomy copy there keeps route metadata, status labels, domain rows, future-provider rows, and CTA labels near existing homepage/platform/trust copy.

Alternatives considered:

  • Separate JSON file: simpler for tabular data but splits page copy from existing localized page copy.
  • Runtime data source: out of scope and would imply a stronger product truth than a website-only claim taxonomy.
  • Hardcoded component arrays: acceptable for narrow content, but weaker for German/English parity.

Decision: Use website-only status labels

Rationale: The public taxonomy needs visible buyer-facing statuses: Current focus, Planned domain, Architecture direction, Not currently available, and Not claimed, with German equivalents. These labels are presentation/content truth only and must not become runtime enums, provider capability states, or persisted product data.

Alternatives considered:

  • No status labels: leaves current/planned/future claims ambiguous.
  • Detailed public roadmap stages: creates stronger commitment and governance overhead than needed.
  • Runtime capability registry: explicitly out of scope and unnecessary for public claim discipline.

Decision: Default uncertain Microsoft-adjacent domains to planned-domain wording

Rationale: The spec requires repo/product truth before marking a domain current. In planning, only Intune/Microsoft 365 positioning is safe as current public focus. Entra, Conditional Access, SharePoint/OneDrive, Enterprise Apps, Service Principals, Security Posture Evidence, Provider Permissions, and Review Packs should default to planned-domain wording unless implementation verifies current availability.

Alternatives considered:

  • Mark all Microsoft domains current: risks false capability claims.
  • Mark all adjacent domains not available: too conservative and obscures roadmap direction.
  • Use architecture direction for all non-Intune domains: less useful for Microsoft 365 domain roadmap clarity.

Decision: Default Google/AWS/Okta to architecture direction

Rationale: The public page may explain provider-extensible design, but Google Workspace, Google Cloud, AWS, Okta, and other SaaS systems must not look live unless verified. Architecture-direction wording communicates future possibility without support claims.

Alternatives considered:

  • Omit non-Microsoft providers: avoids risk but fails the spec's goal of explaining future provider direction.
  • Mark as planned domains: too close to a roadmap commitment.
  • Use official logos or integration badges: rejected because they imply partnership or availability.

Decision: Reuse current Playwright smoke coverage patterns

Rationale: Existing website smoke tests already check public routes, metadata, links, placeholder URLs, claim guardrails, horizontal overflow, mobile navigation, and localized routes. Extending those tests is the narrowest proof for a static website taxonomy.

Alternatives considered:

  • Add Laravel/Pest tests: wrong layer; platform runtime is out of scope.
  • Add dedicated unit tests for copy objects: more brittle than route-level public behavior for this feature.
  • Manual-only smoke: insufficient for claim guardrails and route metadata regression.

Decision: Validate with existing package scripts only

Rationale: /Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/package.json exposes build, test, test:smoke, format:check, and related scripts. The plan should not invent check; the build script already runs astro check before astro build.

Alternatives considered:

  • pnpm --filter @tenantatlas/website check: not present in current package scripts.
  • Root script changes: explicitly out of scope and would break workspace contracts.
  • Platform/Sail commands: wrong scope for public website-only work.

Decision: Use static claim scans as implementation blockers

Rationale: The feature exists to prevent overclaiming. Static scans for href="#", Google supported, AWS supported, Okta supported, multi-cloud supported, all cloud providers, universal policy governance, Intune Management Tool, automatic remediation, automatic restore, real-time drift, immutable backups, gerichtsfeste Nachweise, and lueckenlose Evidenz should run against website source and public assets, and against generated output if committed.

Alternatives considered:

  • Rely only on code review: too easy to miss SEO/meta or generated HTML phrasing.
  • Block every provider name: not correct; provider names are allowed when framed as architecture direction.
  • Add a new linter: unnecessary for one bounded website feature.