ahmido
09dc9988cb
## 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
92 lines
6.3 KiB
Markdown
92 lines
6.3 KiB
Markdown
# 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.
|