TenantAtlas/specs/213-website-foundation-v0/research.md

Research: Initial Website Foundation & v0 Product Site

Decision 1: Keep apps/website as a fully static Astro 6 site

• Decision: Keep Astro 6 in static-output mode and preserve hard runtime separation from apps/platform.
• Rationale: The website is a trust-first product site, not an application surface. Static output keeps the site fast, cacheable, SEO-friendly, and operationally independent from Laravel, Filament, tenant state, and platform auth/session concerns.
• Alternatives considered:
  • SSR or hybrid rendering: rejected because v0 does not need per-request logic and it would blur the separation between website and platform.
  • A single ad hoc landing page refresh: rejected because it would not establish the reusable v0 website foundation required by the spec.

Decision 2: Add explicit TypeScript and Tailwind CSS v4

• Decision: Introduce explicit TypeScript setup in apps/website and adopt Tailwind CSS v4 using the CSS-first configuration model.
• Rationale: The site needs a maintainable foundation for multiple routes, reusable primitives, and later content expansion. TypeScript makes component props, metadata, and content structures safer; Tailwind v4 scales layout and typography decisions better than continued page-local CSS growth.
• Alternatives considered:
  • Keep handwritten global CSS only: rejected because the page count and reusable-section scope in v0 would quickly turn styling into duplicated local CSS islands.
  • Delay TypeScript: rejected because the feature explicitly introduces a reusable component layer and content helpers that benefit from typed contracts immediately.

Decision 3: Do not introduce React for v0

• Decision: Do not add React as part of Spec 213.
• Rationale: React is not required to deliver the v0 product site, and it adds framework, hydration, and dependency cost without solving a concrete launch problem. Astro already supports a static-first component model that fits the site’s reading, navigation, and CTA flows.
• Alternatives considered:
  • React islands for all UI: rejected because it introduces unnecessary client framework weight for a content-driven public site.
  • “Add React now for future flexibility”: rejected under PROP-001 and ABSTR-001 because future optional interactivity is not enough reason to pay the cost in v0.

Decision 4: Use custom shadcn-inspired Astro primitives instead of official shadcn/ui

• Decision: Use a custom Astro-native design-system layer inspired by shadcn/ui conventions rather than installing React plus official shadcn/ui.
• Rationale: The product needs an intentional, enterprise-credible public surface. Astro-native primitives keep ownership local, avoid framework coupling, and still allow the team to use shadcn-like conventions for buttons, cards, inputs, badges, sheets, tabs, and dialogs if needed later.
• Alternatives considered:
  • Full React + official shadcn/ui: rejected because it solves a speed-of-assembly problem at the cost of unnecessary framework/runtime complexity.
  • Ported third-party Astro shadcn clones: rejected because they split ownership and can still impose design decisions broader than the feature needs.

Decision 5: Keep Contact / Demo static in v0

• Decision: Treat Contact / Demo as a static conversion surface in Spec 213. The page may point to a controlled external/manual intake path, but Spec 213 does not introduce an internal website backend or API contract for form submission.
• Rationale: The feature goal is to establish a trustworthy public site foundation, not to solve CRM or submission pipeline architecture. Keeping the contact surface static avoids backend/runtime coupling and leaves room for a later explicit decision on form handling.
• Alternatives considered:
  • Build an Astro endpoint or app-backed form now: rejected because form handling is still an open product/ops decision and is not required to make the v0 site credible.
  • Omit contact intent entirely: rejected because the spec requires a clear conversion path.

Decision 6: Public route structure should be small, explicit, and future-ready

• Decision: Publish the core route set now and organize the source tree so docs/blog/changelog can be added later without rewriting the live page hierarchy.
• Rationale: The v0 website needs clarity more than breadth. A small public sitemap makes the product understandable now while avoiding future structural dead ends.
• Alternatives considered:
  • Publish docs/blog/changelog placeholders now: rejected because dead or thin routes reduce trust.
  • Keep all content in one giant home page: rejected because Product, Solutions, Trust, Integrations, and Contact need distinct narrative roles.

Decision 7: Use lightweight browser smoke validation plus build proof

• Decision: Keep validation in fast-feedback with root build proof and a small Playwright browser smoke suite local to apps/website.
• Rationale: Build proof alone does not catch broken routes, broken navigation, or browser-visible regressions. A tiny smoke suite gives real confidence without importing backend fixtures or a heavy end-to-end lane.
• Alternatives considered:
  • Build-only validation: rejected because it can still ship broken pages.
  • Heavy end-to-end coverage: rejected because the site has no authenticated workflow or backend interaction that justifies it.

Baseline Findings

• apps/website currently uses Astro 6 with output: 'static'.
• The current site consists of a single index.astro, a minimal BaseLayout.astro, and handwritten global CSS.
• No TypeScript setup, Tailwind install, React integration, or dedicated website test tooling is currently present.
• Root workspace contracts already expose corepack pnpm dev:website and corepack pnpm build:website, and those must remain intact.