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.