TenantAtlas/specs/215-website-core-pages/research.md

Research: Website Information Architecture / Core Pages

Decision 1: Preserve the website working contract and keep all IA truth local to apps/website

• Decision: Treat Spec 215 as a website-only IA change inside apps/website and preserve @tenantatlas/website, WEBSITE_PORT, Astro static output, and the root dev:website / build:website workflows unchanged.
• Rationale: The spec is explicitly scoped to the public website and excludes platform routing, auth, and Filament concerns. The narrowest correct implementation is therefore to evolve the existing Astro app in place without introducing backend, package, or runtime coupling to apps/platform.
• Alternatives considered:
  • Introduce shared website-platform routing or metadata contracts: rejected because the spec explicitly excludes apps/platform obligations.
  • Solve IA through platform-side redirects or a shared CMS: rejected because the website already has a self-contained Astro route layer that can carry the IA truth directly.

Decision 2: Use the existing site.ts and route-definition layer as the canonical IA source of truth

• Decision: Reuse apps/website/src/lib/site.ts, apps/website/src/types/site.ts, and apps/website/src/content/pages as the canonical source of truth for core routes, page roles, navigation, footer groupings, CTA hierarchy, and page-family mapping.
• Rationale: The current website already centralizes navigation, page definitions, shell tone, CTA variants, and sitemap route generation in the site.ts layer. Extending that layer is the narrowest way to encode the new IA without introducing a second route manifest or a CMS-style navigation system.
• Alternatives considered:
  • Create a second IA-only config file: rejected because it would duplicate route truth and increase drift risk.
  • Hardcode navigation and page-role decisions separately inside each page component: rejected because it would repeat the current v0 problem in a less controllable form.

Decision 3: Canonicalize the required core route set and use compatibility paths only when necessary

• Decision: Treat /, /product, /trust, /changelog, /contact, /privacy, and /imprint as the canonical core route set for the initial website. Replace /security-trust with /trust as the canonical trust path, add /changelog, add /imprint, and keep compatibility paths narrow and temporary if route renames would otherwise cause avoidable breakage.
• Rationale: The current route inventory contains /security-trust instead of /trust and lacks both /changelog and /imprint, even though the spec requires a small, enterprise-credible core that includes visible trust, visible product progress, and legal basics. Canonicalizing these paths aligns the implementation with the spec while keeping change scope focused on the website route layer.
• Alternatives considered:
  • Keep /security-trust as the long-term canonical path: rejected because the spec names /trust and the shorter path is clearer.
  • Add /changelog and /imprint only as footer labels without real routes: rejected because the spec requires actual public surfaces, not navigation placeholders.
  • Preserve every old route as a permanent parallel surface: rejected because multiple canonical truths would dilute the IA and make future page work harder.

Decision 4: Keep primary navigation intentionally small and demote non-core v0 routes

• Decision: Shrink primary navigation to the Spec 215 core: Product, Trust, Changelog, Contact, plus optional Resources only when substantive content exists. Treat Solutions and Integrations as retained secondary supporting pages rather than core IA peers.
• Rationale: The current primary navigation already consumes all 5 available informational slots with Product, Solutions, Security & Trust, Integrations, and Contact, leaving no room for Changelog even though product progress is a first-class public signal in Spec 215. If the IA stays small, solutions-style audience framing must live inside Home/Product first, while already-published supporting pages such as Solutions and Integrations can remain secondary without occupying core nav space.
• Alternatives considered:
  • Keep Solutions and Integrations in top-level nav and simply add Changelog as a 6th item: rejected because the spec explicitly prioritizes a small navigation and core-route discipline.
  • Remove outcome explanation entirely when demoting Solutions: rejected because the spec requires buyer-oriented outcome explanation even without a dedicated /solutions hub.

Decision 5: Use Astro content collections as readiness gates for optional surfaces

• Decision: Treat the existing resources and changelog Astro content collections as the current readiness mechanism for optional and recommended public surfaces. The existing articles collection remains unpublished until a separate editorial/blog spec activates it. /changelog is special: it is part of the recommended core and therefore needs substantive dated entries rather than an empty shell.
• Rationale: The repo already has empty content collections for articles, changelog, and resources. Using resources and changelog as explicit discoverability gates avoids empty prestige routes, while leaving articles unpublished prevents the current IA from implying an activated blog/editorial surface that does not yet exist.
• Alternatives considered:
  • Publish /blog or /resources immediately as placeholders because collections already exist: rejected because the spec forbids empty prestige pages.
  • Ignore the existing content collections and hand-build separate page data sources: rejected because it would bypass the narrowest existing structure.

Decision 6: Validate the IA through route-aware smoke coverage and build proof

• Decision: Keep validation in fast-feedback using corepack pnpm build:website and the existing Playwright smoke suite in apps/website/tests/smoke, expanded to cover the canonical core routes, updated nav/footer labels, optional-surface suppression, and any compatibility-route expectations.
• Rationale: The feature changes route topology, navigation, footer grouping, and discoverability rules on a static Astro site. The current smoke suite already verifies shell structure, navigation labels, CTA hierarchy, and footer links; expanding those helpers is the smallest realistic proof of the new IA.
• Alternatives considered:
  • Build-only validation: rejected because it would miss browser-visible regressions in navigation labels, hidden/visible route links, and compatibility paths.
  • Heavier browser or cross-browser infrastructure: rejected because the public website remains static-first and the current smoke suite is sufficient for this route-contract feature.

Baseline Findings

• apps/website is a standalone Astro 6 app with static output, strict TypeScript, Tailwind CSS v4, and local Playwright smoke coverage.
• The current public route inventory is /, /product, /solutions, /security-trust, /integrations, /contact, /legal, /privacy, and /terms.
• The current primary navigation is driven from src/lib/site.ts and uses Product, Solutions, Security & Trust, Integrations, and Contact as the five informational links.
• The current footer also comes from src/lib/site.ts and groups Explore, Next step, and Legal links around the v0 route set.
• The current page-definition layer already models page roles, families (landing, trust, content), shell tones, header CTA variants, and footer lead variants.
• Astro content collections for articles, changelog, and resources already exist; the current plan activates changelog, reserves resources as the only optional content surface in this feature, and leaves articles unpublished.
• The current smoke suite already covers Home, Product, Solutions, Security & Trust, Integrations, Contact, and legal surfaces, so route-topology regression proof can stay inside the existing website test harness.