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.