웹 서피스

Schift 웹 애플리케이션은 Astro 프로젝트로, 브라우저에 노출되는 하나의 웹 서피스(Web Surface) 아래에 공개 마케팅 페이지, 현지화된 문서, SEO 콘텐츠, 인증된 대시보드를 제공합니다.

라우트(Route) 맵

라우트	용도
`/`, `/pricing`	마케팅 랜딩 페이지
`/docs/*`	퀵스타트, SDK, CLI, 개념, 웹 레퍼런스를 위한 문서 셸
`/blog/`, `/compare/`, `/guides/*`	SEO 및 교육 콘텐츠
`/ko/`, `/jp/`	한국어와 일본어를 위한 현지화된 진입점
`/app`, `/app/workflows`, `/app/oauth-callback`	인증된 대시보드 셸 및 워크플로우 빌더 진입점

참고: /app/* 라우트는 인증이 필요하므로 공개 사이트맵에서 제외됩니다.

스택(Stack) 및 런타임(Runtime)

구성 요소	현재 선택
사이트 프레임워크	Astro 6
인터랙티브 UI	React 19
스타일링	Tailwind CSS 4와 로컬 UI 프리미티브
현지화(Localization)	Astro i18n, `en`, `ko`, `jp` 지원
배포 대상	Cloudflare Pages, `npm run build`의 `dist/` 출력

로컬 개발

요구 사항:

Node.js >=22.12.0
npm

cd schift-web
npm install
npm run dev

기본 개발 서버는 http://127.0.0.1:4324에서 실행됩니다. 별도의 포트에서 Connect 서피스(Surface)를 실행하려면:

npm run dev:connect

Connect는 기본적으로 http://127.0.0.1:4325를 사용합니다.

런타임 설정

웹 앱은 API 요청과 빌드 시점 SEO 아티팩트(artifact)를 위해 브라우저에 노출된 환경 변수(environment variable)를 읽습니다.

변수	용도
`PUBLIC_API_URL`	제품 API 오리진(origin)
`PUBLIC_AUTH_API_URL`	인증 API 오리진(로컬 호환성을 위해 `PUBLIC_API_URL`로 폴 백)
`PUBLIC_CONNECT_ORIGIN`	로그인 후 복귀 대상으로 허용할 Connect 앱 오리진
`PUBLIC_COOKIE_DOMAIN`	앱과 Connect 하위 도메인이 공유하는 인증 쿠키 도메인
`PUBLIC_COOKIE_PREFIX`	대시보드 인증에 사용되는 JS에서 읽을 수 있는 CSRF 쿠키의 접두사
`PUBLIC_SSO_SECURITY_URL`	2단계 인증 설정에서 연결할 계정 보안 페이지 HTTPS URL
`PUBLIC_GA_MEASUREMENT_ID`	Google Analytics 측정 ID(비운영 빌드용 오버라이드)
`PUBLIC_SITE_URL`	빌드 시점에 필요한 정규 공개 웹 오리진
`PUBLIC_WIDGET_BROWSER_URL`	위젯 HTML 삽입 코드에 표시할 브라우저 모듈 URL
`PUBLIC_WIDGET_NPM_PACKAGE`	React/Next 위젯 설치 코드에 표시할 NPM 패키지 이름

참고: 프로덕션 환경에서 PUBLIC_API_URL과 PUBLIC_AUTH_API_URL을 모두 설정하지 않으면, 웹 앱의 서로 다른 부분이 다른 백엔드와 통신할 수 있습니다.

대시보드 인증은 백엔드가 설정한 httpOnly 쿠키와 PUBLIC_COOKIE_PREFIX에서 파생된 JS에서 읽을 수 있는 CSRF 및 복귀 경로 쿠키를 함께 사용합니다. 앱과 Connect가 같은 상위 도메인을 공유할 때만 PUBLIC_COOKIE_DOMAIN을 설정하고, Connect가 로그인 후 자기 오리진으로 사용자를 돌려보내야 할 때 PUBLIC_CONNECT_ORIGIN을 설정합니다.

프로젝트 경계

웹 리포지토리는 브라우저에 노출되는 UI만 담당합니다. 재사용 가능한 제품 계약(contract)은 schift-api에, 소스 동기화 실행은 schift-worker에, 검색 동작은 schift-db에 있습니다.

서피스	위치	책임
공개 사이트	`apps/www`	마케팅, 문서, 가격, 콘텐츠 라우트
대시보드	`apps/app`	인증된 제품 화면 및 `/app/api/*` BFF 핸들러
Connect/온볼딩	`apps/connect`	소스 선택, OAuth 핸드오프, 사업자 등록, `/connect/api/*` BFF 핸들러

참고: 웹 리포지토리에 재사용 가능한 API 계약(contract)을 두지 마세요. 웹 로컬 핸들러는 세션 부트스트랩, OAuth 리턴, 온볼딩 임시 상태, 화면 특정 집계에만 사용됩니다.

배포

사이트는 정적 Astro 사이트로 빌드됩니다. Cloudflare Pages는 wrangler.toml에 설정된 생성된 dist/ 디렉토리를 제공합니다.

npm run build
npm run preview

참고: 프로덕션 빌드는 올바른 SEO 아티팩트(artifact)를 생성하기 위해 PUBLIC_SITE_URL이 필요합니다.