# FeatPaper Tech Stack Decision

## Decision

v1 기준 스택은 `Astro + React Islands + MDX + Cloudflare Pages`로 확정한다.

v1은 static-first 사이트로 만든다. 제품 운영에 필요한 콘텐츠, Use Case, Magazine, Roadmap, Plugin 페이지는 MDX와 structured data를 통해 PR 기반으로 운영한다.

## Why Astro

- v1의 핵심은 서버 앱이 아니라 콘텐츠 운영, 정적 SEO, 빠른 preview, PR 단위 안전한 변경이다.
- Astro는 정적 페이지 중심의 제품/콘텐츠 사이트에 적합하다.
- MDX와 Content Collections가 Use Case, Magazine, Plugin, Roadmap 운영 모델에 잘 맞는다.
- React Islands를 통해 실제 상호작용이 필요한 부분만 React로 만들 수 있다.
- Cloudflare Pages의 정적 배포 모델과 잘 맞는다.

## Why Not Next.js for v1

Next.js + OpenNext는 Later 옵션으로 둔다.

다음 요구가 실제로 커질 때 재검토한다.

- CRM과 직접 연결된 개인화 흐름
- 인증 기반 제품 표면
- 사용자별 서버 렌더링
- 서버 액션 또는 API route 중심의 제품 통합
- 복잡한 webhook 처리와 내부 DB 연동

PR0 기준으로는 위 요구가 v1 필수 범위가 아니므로 Next.js, OpenNext, Cloudflare Workers, Supabase, CRM은 도입하지 않는다.

## Rendering and Hosting Model

- Rendering: static-first
- Hosting: Cloudflare Pages
- Framework preset: `Astro`
- Build command: `npm run build`
- Build output directory: `dist`

v1에서는 Cloudflare server routes 또는 Workers를 사용하지 않는다. Tally 폼은 embed 또는 external link로 사용하고, 저장/운영 가시성은 Tally + Google Sheets로 처리한다.

## Content Collections

Astro Content Collections는 다음 컬렉션을 기준으로 설계한다.

- `useCases`
- `magazine`
- `plugins`
- `roadmap`
- `releases`
- `pages`

각 컬렉션은 PR3에서 frontmatter schema와 validation을 갖춘다. 예상 필드는 locale, slug, title, description, category, tags, relatedFeatures, relatedPlugins, ctaType, publishedAt, updatedAt, ogImage, canonical, draft 여부다.

## Structured Data Under `src/data`

`src/data`는 반복 가능한 운영 데이터를 관리한다.

- navigation
- footer
- CTAs
- forms
- feature modules
- home modules
- tracking taxonomy

이 데이터는 화면 구현과 콘텐츠 운영 사이의 계약이다. PR3에서 schema validation을 추가하고, PR4 이후 페이지 구현은 이 데이터 구조를 우선 사용한다.

## React Islands Policy

React Islands는 실제 상호작용이 있는 표면에만 사용한다.

- `FeatureTabs`
- `RoadmapBoard`
- `MagazineFilter`
- `TallyEmbed`
- `LanguageSwitcher` if needed

정적 카드, 단순 CTA, 일반 레이아웃, MDX article body는 Astro 컴포넌트를 기본으로 한다. React를 기본 UI 레이어로 확장하지 않는다.

## Assets Policy

- `assets/raw`는 원본 보관소이며 배포하지 않는다.
- 실제 사용 asset은 이후 PR에서 `assets/selected`로 선별한다.
- production asset은 사용 전에 크기, 포맷, alt, lazy loading, responsive sizing을 검토한다.
- raw asset 전체를 public 경로로 노출하거나 일괄 최적화하지 않는다.
- PR0에서는 asset 이동, 삭제, 최적화, 배포 준비를 하지 않는다.

## Feedback and Data Policy

v1 feedback/data loop는 Tally + Google Sheets로 운영한다.

사용처는 다음이다.

- 업데이트 구독
- 기능 요청
- 로드맵 관심 등록
- 기업 도입 문의
- Use Case 제보

Supabase, CRM, internal DB는 Later 옵션이다. PR0에서는 DB schema, backend, webhook 처리, analytics SDK를 도입하지 않는다.

## Validation Policy

프로젝트가 PR1 이후 scaffold되면 다음 검증을 표준으로 둔다.

- build
- typecheck
- content validation
- internal route link check
- Tally link check
- FeatPaper product link check
- plugin marketplace link check
- layout smoke check for layout-heavy PRs

PR0는 scaffolding 전 docs-only 작업이므로 `git diff --check`를 최소 검증으로 수행한다. repo에 markdown lint script가 생기면 문서 PR에서 함께 실행한다.

## Revisit Triggers

다음 조건이 발생하면 기술 결정을 재검토한다.

- 서버 기반 개인화가 전환 성과에 직접 필요해진다.
- 제품 로그인 상태와 웹사이트 페이지가 연결되어야 한다.
- Tally + Google Sheets가 운영 병목이 된다.
- 콘텐츠 운영자가 PR 기반 workflow만으로 운영하기 어렵다는 증거가 쌓인다.
- 다국어 콘텐츠 규모가 커져 별도 CMS 또는 translation workflow가 필요해진다.
- analytics SDK나 CRM 연동이 제품 운영 루프의 필수 입력이 된다.