TenantAtlas/specs/401-tenantial-platform-page/research.md

# Phase 0 Research: Tenantial Platform Page

## Decision: Keep the feature inside the standalone Astro website

**Rationale**: The active spec is public website-only. The repository already has a standalone Astro app at `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website` with typed content modules, reusable layout components, Tailwind v4 styling, SEO helpers, and Playwright smoke tests. Keeping the work there preserves the boundary from the Laravel platform app.

**Alternatives considered**:

- Change `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/platform`: rejected because the spec excludes Laravel, Filament, Livewire, auth, APIs, database, queues, and runtime tenant data.
- Add a separate website package or docs system: rejected because the existing Astro website already supports the needed static route and public shell.

## Decision: Make `/platform` the canonical route

**Rationale**: The feature is explicitly a Tenantial Platform page and Spec 400 created an "Explore the platform" journey. A canonical `/platform` route is clearer for buyers than retaining `/product` as the primary destination.

**Alternatives considered**:

- Keep `/product` as primary: rejected because the spec asks for `/platform` and the current homepage CTA should become a clean platform journey.
- Remove `/product` immediately with no compatibility: rejected because the route already exists and current tests/navigation may still reference it during the transition.

## Decision: Treat `/product` as redirect-only compatibility

**Rationale**: The current repository has `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/pages/product.astro` and `/Users/ahmeddarrazi/Documents/projects/wt-website/apps/website/src/content/pages/product.ts`. The narrowest safe path is to keep `/product` reachable while preventing stale or conflicting copy by redirecting it to `/platform`. This avoids maintaining two renderable public product pages or duplicate metadata during the transition.

**Alternatives considered**:

- Leave `/product` unchanged: rejected because it would create route confusion and keep homepage/platform semantics split.
- Delete `/product` in the same slice: rejected because it can break existing public links and smoke tests without adding product value.
- Render equivalent Platform content at `/product`: rejected because it keeps a second renderable product page and makes metadata/canonical drift more likely than redirect-only compatibility.

## Decision: Store Platform page content in a typed static content module

**Rationale**: Existing public pages use `apps/website/src/content/pages/*.ts` to hold SEO and page content, then render through `apps/website/src/pages/*.astro`. A new `platform.ts` content module matches the current pattern and keeps static copy centralized without adding a CMS or new data source.

**Alternatives considered**:

- Put all copy inline in `platform.astro`: rejected because it would diverge from current website content conventions.
- Add a CMS or content collection for the Platform page: rejected because the spec excludes CMS complexity.

## Decision: Reuse existing website shell, primitives, and section components first

**Rationale**: Existing components already cover PageShell, Navbar, Footer, PageHero, FeatureGrid, CTASection, Section, Container, Grid, Card, Badge, and CTA primitives. Reusing them keeps Spec 401 aligned with Spec 400 and avoids a parallel public-site component language.

**Alternatives considered**:

- Create a full new Platform page component system: rejected as unnecessary abstraction for one route.
- Use a large raster screenshot as the primary visual: rejected because no approved Tenantial product screenshot exists and the spec prohibits fake live data.

## Decision: Use static diagrams and structured panels for the platform model

**Rationale**: The page needs to explain operating model, governance loop, truth layers, and boundaries without implying live tenant data. Static HTML/CSS/SVG-like structure or existing panel/card components can communicate the model accessibly and keep performance simple.

**Alternatives considered**:

- Use real tenant screenshots: rejected because no approved customer or tenant environment assets are available.
- Use heavy animation or diagram libraries: rejected because the spec requires mostly static content and no unnecessary client-side JavaScript.

## Decision: Update site route definitions and navigation metadata

**Rationale**: `apps/website/src/lib/site.ts` owns primary navigation, footer navigation, route definitions, canonical routes, and sitemap inclusion. Adding `/platform` there keeps header/footer/sitemap/canonical behavior consistent with current site conventions.

**Alternatives considered**:

- Hardcode `/platform` only in page files: rejected because header/footer and smoke helpers would remain inconsistent.
- Add a second route registry: rejected as needless parallel state.

## Decision: Keep "Book a demo" pointed at the existing contact route

**Rationale**: The current public conversion path is `/contact`, and the spec excludes a demo-booking backend. Reusing `/contact` keeps CTA behavior intentional and avoids fake form behavior.

**Alternatives considered**:

- Create `/demo` or `/pricing`: rejected because those pages/flows are out of scope.
- Use a dead placeholder link: rejected because the spec requires intentional, working CTA destinations.

## Decision: Expand website smoke coverage and explicitly close repository-wide gates

**Rationale**: The feature changes a public static route, navigation, metadata, copy safety, and responsive behavior. Existing Playwright smoke tests are the correct feature proof surface. No new Laravel/Pest/database/Filament product test should be introduced because no platform behavior changes. Repository-wide close-out still runs a targeted existing Pest hygiene check plus Pint dirty formatting before finalization.

**Alternatives considered**:

- Add platform feature tests: rejected because they would introduce unrelated setup and false confidence for a website-only route.
- Add broad visual regression infrastructure: rejected because this feature only needs focused route/content/mobile smoke coverage.

## Decision: Preserve conservative public claim boundaries

**Rationale**: Tenantial's public trust depends on avoiding unsupported claims. The page should use language such as evidence-oriented, reviewable decisions, recovery context, operator confirmation, and traceable records while avoiding certifications, guarantees, named customers, Microsoft endorsement, and real-time claims unless approved evidence exists.

**Alternatives considered**:

- Use stronger enterprise proof language for sales impact: rejected because unsupported claims create trust and compliance risk.
- Omit boundaries entirely: rejected because the page must clarify that Tenantial is not a helpdesk, SIEM, device action tool, or Microsoft admin center replacement.

## Decision: No unresolved clarifications remain

**Rationale**: The current repository answers the planning unknowns: Astro website exists, `/product` exists, `/platform` does not yet exist, navigation points to `/product`, smoke tests exist, and `/contact` is the current conversion path.

**Alternatives considered**:

- Ask for route/CTA clarification: rejected because the spec provides reasonable defaults and current repository state supports a safe path.