인터랙티브 사이트 아키텍처

인터랙티브 사이트 아키텍처은(는) 무엇을 하나요?

결과

콘텐츠, 내러티브, 시각적 아이덴티티 및 상호작용 품질이 중요한 프로덕션 공개용 Next.js 사이트를 만듭니다. 이는 콘텐츠 중심 사이트를 위한 범용 아키텍처입니다: 브랜드 및 마케팅 사이트, SaaS 및 제품 사이트, 런칭 페이지, 에디토리얼, 포트폴리오, 커뮤니티, 컨퍼런스, 문서형 사이트 및 몰입형 쇼케이스.

핵심은 고정되어 있습니다:

• 서버 렌더링 콘텐츠
• 좁은 클라이언트 아일랜드
• 검증된 콘텐츠 계약
• 공유 디자인 및 모션 토큰
• 네이티브 브라우저 동작
• 서버 응답 내 SEO 및 접근성
• 경로 범위 성능 예산

제품에 필요한 모듈을 선택하십시오:

모듈	사용 시기
콘텐츠 컬렉션 및 상세	사이트에 프로젝트, 기사, 제품, 인물, 이벤트 등 유사한 레코드가 있는 경우
포트폴리오 또는 케이스 스터디	조직이 작업을 통해 증명이 필요한 경우
몰입형 아카이브	시각적 탐색이 주요 제품 표면인 경우
스토어	사이트에서 디지털 또는 물리적 제품을 판매하는 경우
CMS 어댑터	편집자가 릴리스와 관계없이 독립적으로 게시하는 경우
연락처 양식	메일 링크나 캘린더로 충분하지 않은 경우

필요하지 않은 사이트에 선택적 모듈을 강제로 도입하지 마십시오.

일반적인 프로필은 동일한 핵심을 재사용합니다:

• SaaS 또는 제품: 랜딩, 오퍼, 기능, 콘텐츠 컬렉션, 문서 또는 변경 로그.
• 브랜드 또는 런칭: 캠페인 내러티브, 제품 공개, 대기자 명단, 사회적 증명.
• 에디토리얼: 컬렉션 색인, 기사 상세, 작성자, 주제, 검색.
• 커뮤니티 또는 컨퍼런스: 발표자, 일정, 세션, 장소, 티켓.
• 포트폴리오: 프로젝트 색인, 케이스 상세, 시각적 아카이브, 연락처.
• 커머스: 카탈로그, 제품 상세, 체크아웃, 다운로드 또는 이행.

행동 전 읽기

• 모든 빌드, 리디자인 또는 아키텍처 변경 시 references/architecture-contract.md를 읽으십시오.
• 폴더, 계약, 서비스, 어댑터 또는 서버 액션을 만들기 전에 references/code-architecture.md를 읽으십시오.
• 의존성을 설치, 업그레이드 또는 제거하기 전에 references/dependency-matrix.md를 읽으십시오.
• 새로운 애플리케이션의 경우 references/build-playbook.md를 따르십시오.
• 새로운 경로, 콘텐츠 유형, 아일랜드, 아카이브, 스토어 제품 또는 마이그레이션의 경우 references/evolve-playbook.md를 따르십시오.
• 승인 또는 릴리스 전에 references/quality-gates.md를 따르십시오.

재사용 가능한 템플릿은 assets/templates/ 아래에 있습니다. 선택한 아키텍처와 일치할 때만 템플릿에서 시작하십시오. 모든 템플릿을 맹목적으로 복사하지 마십시오.

비협상 불변 규칙

1. 페이지 구성과 기본 콘텐츠는 기본적으로 Server Component에 유지하십시오.
2. use client는 가능한 가장 작은 잎(leaf)에 배치하십시오. 가능할 때 클라이언트 래퍼를 통해 서버 렌더링된 자식을 애니메이션화하십시오.
3. TypeScript 데이터 계약을 모든 콘텐츠 엔티티, 메타데이터 레코드, 갤러리 및 사이트맵 항목에 대한 단일 진실 공급원으로 취급하십시오.
4. 모든 오버레이 상호작용에 클라이언트 상태, JavaScript 또는 해시 없이 작동하는 실제 경로를 제공하십시오.
5. 기본 HTML 동작을 먼저 사용하십시오: 링크, 버튼, 양식, <dialog>, 포커스 관리 및 브라우저 기록.
6. 비밀은 서버 전용 모듈에 보관하십시오. NEXT_PUBLIC_*는 공개 식별자만 사용할 수 있습니다.
7. 커머스가 존재하는 경우, 가격, 자격 결정, 결제 확인 및 보호된 다운로드를 서버에서 유지하십시오.
8. prefers-reduced-motion, 키보드 탐색, 가시적 포커스, 의미론적 제목 및 스크립트 없이 읽기 가능을 존중하십시오.
9. 한 경로의 콘텐츠를 다른 경로의 초기 클라이언트 번들에 포함시키지 마십시오. 클라이언트 셸이 개수나 레이블이 필요할 때 서버에서 작은 요약을 전달하십시오.
10. 얇은 경로 어댑터, 소유 기능 모듈, 명시적 포트 및 단일 구성 경계를 가진 모듈식 모놀리스를 사용하십시오.
11. 안정적인 의존성을 선호하십시오. 문서화된 이유 없이 카나리 React 빌드로 새 프로덕션 앱을 시작하지 마십시오.

기본 스택

사이트에 문서화된 차이가 없는 한 의존성 매트릭스의 정확한 검증된 버전을 사용하십시오.

• Node 26 LTS 패밀리 및 pnpm.
• Next.js App Router, React, React DOM, TypeScript.
• Tailwind CSS 4 (토큰, 리셋 및 유틸리티 레이아웃용).
• CSS Modules (경로 또는 컴포넌트별 구성을 위해).
• Motion for React (오케스트레이션 및 제스처용).
• Native dialog, Canvas, SVG, CSS 및 Web Animations API (충분할 때 상호작용용).
• Lucide 아이콘 (개별적으로 가져오기).
• Zod (콘텐츠 및 외부 입력 경계용).
• Vercel (배포, 분석 및 이미지 전송용).
• Stripe Embedded Checkout 및 서버 액션 (커머스가 필요할 때).

작업 순서

1. 공개 표면을 목록화하십시오: 랜딩 페이지, 콘텐츠 색인, 상세 경로, 전환 경로, 법적 경로, 검색, 아카이브 및 커머스.
2. 구현 전에 경로 매니페스트와 클라이언트 경계 맵을 확정하십시오.
3. 파일을 만들기 전에 기능 소유자, 포트, 경로 어댑터 및 외부 어댑터를 할당하십시오.
4. 섹션을 만들기 전에 콘텐츠 엔티티와 필요한 미디어를 모델링하십시오.
5. 전역 토큰, 타이포그래피, 간격, 상태, 축소 모션 동작 및 이미지 규칙을 설정하십시오.
6. 서버 셸, 내비게이션, 경로 폴백 및 SEO 메타데이터를 구축하십시오.
7. 한 번에 하나씩 클라이언트 아일랜드를 추가하십시오. 각각이 클라이언트 측이어야 하는 이유를 기록하십시오.
8. 네이티브 dialog와 URL 상태로 오버레이를 구축하십시오. 동시에 표준 페이지 경로를 추가하십시오.
9. 데이터, 폴백, 축소 모션 동작 및 성능 한계가 정의된 후에 복잡한 시각 요소를 추가하십시오.
10. 운영 모델이 필요로 할 때만 CMS, 커머스, 계정 또는 지속성을 추가하십시오.
11. 아키텍처 경계 검사, 구조 감사, 집중 테스트, 품질 게이트 및 프로덕션 미리보기 승인을 실행하십시오.
12. 구현된 동작, 검증된 증거 및 확인되지 않은 제한 사항을 별도로 보고하십시오.

결정 규칙

• 호버, 포커스, 프레스, 리빌, 마키(marquee) 및 간단한 상태 변경에는 CSS 전환을 사용하십시오.
• 조정된 변형, 레이아웃 전환, 드래그, 프레즌스(presence) 및 스크롤 연결 오케스트레이션에는 Motion을 사용하십시오.
• Canvas 또는 WebGL은 DOM, SVG 및 CSS로 안정적으로 표현할 수 없는 시각 요소에만 사용하십시오. 가시성 일시 중지, DPR 제한, 정리, 축소 모션 동작 및 정적 폴백을 추가하십시오.
• 콘텐츠 컬렉션을 서버 렌더링 상태로 유지하십시오. 클라이언트 오버레이 셸에는 개수, 레이블 또는 선택된 레코드만 전송하십시오.
• 같은 콘텐츠에 표준 페이지도 있을 때 미리보기 및 시트에는 네이티브 <dialog>를 사용하십시오. 깊고 길거나 독립적으로 링크된 콘텐츠에는 전용 경로를 사용하십시오.
• 앱과 함께 릴리스하는 소규모 팀에는 검증된 코드 콘텐츠를 사용하십시오. 편집자가 독립적인 게시가 필요할 때 리포지토리 어댑터 뒤에 CMS를 도입하십시오.
• 스토어가 즉시 구매 및 다운로드만 필요한 경우 상태 비저장 Stripe 세션을 사용하십시오. 제품에 자격, 환불, 계정, 주문 기록 또는 재시도가 필요할 때 데이터베이스와 검증된 웹훅을 추가하십시오.
• Radix, shadcn 또는 다른 컴포넌트 라이브러리는 소유하는 프리미티브를 식별한 후에만 추가하십시오. 네이티브 요소와 사이트 소유 프리미티브가 기본입니다.
• 포트폴리오, 아카이브 및 스토어를 모듈로 취급하십시오. 이들은 핵심 콘텐츠, 경로, 스타일, 모션 및 보안 계약을 재사용합니다.

필수 빌드 아티팩트

다음 사이트 수준 아티팩트를 만들고 유지 관리하십시오:

• docs/architecture.md: 경로 맵, 클라이언트 경계, 콘텐츠 소유권, 외부 서비스 및 성능 예산.
• src/features/*/domain 및 src/features/*/application: 검증된 계약 및 기능.
• src/platform/*: 외부 어댑터 및 서버 전용 구성 루트.
• src/shared/*: 입증된 교차 기능 계약 및 디자인 프리미티브.
• src/components/*: 서버 구성 및 명시적 이름을 가진 클라이언트 아일랜드.
• src/app/*: 페이지, 레이아웃, 메타데이터, 사이트맵, robots 및 경로 핸들러.
• .env.example: 이름과 용도, 실제 비밀은 절대 포함하지 않음.
• 콘텐츠 검증, 클라이언트 상태 머신, 서버 액션 및 중요한 브라우저 여정에 대한 테스트.
• 미리보기, 브라우저, 접근성, 성능, SEO 및 조건부 커머스 증거가 포함된 릴리스 체크리스트.

구조 감사

스캐폴딩 후 및 릴리스 전에 아키텍처 경계 검사와 번들 감사를 실행하십시오:

pnpm arch:check
node scripts/audit_site.mjs --root /path/to/app

CI에서 경고가 실패해야 하는 경우 --strict를 사용하십시오. 이 스크립트는 의존성 존재, 경로 및 콘텐츠 구조, 클라이언트/서버 비밀 위험, dialog 및 모션 안전 장치, 테스트, SEO 파일 및 소스 맵 노출을 확인합니다. 테스트를 보완하며 대체하지 않습니다.

완료 계약

다음 조건이 충족될 때만 빌드가 완료된 것으로 간주합니다:

• 경로 및 경계 맵이 구현과 일치합니다.
• 의존성 그래프가 순환하지 않고 arch:check가 통과합니다.
• 경로가 기능 공개 API를 사용하고 구성 루트가 와이어링을 소유합니다.
• 앱이 카나리 또는 피어 의존성 문제 없이 빌드됩니다.
• 중요한 콘텐츠가 서버 HTML에 나타납니다.
• 오버레이, 메뉴 및 키보드 경로가 작동하고 포커스를 복원합니다.
• 축소 모션 및 스크립트 없음 폴백이 검증됩니다.
• 메타데이터, 사이트맵, robots, 표준 URL 및 소셜 이미지가 존재합니다.
• 초기 경로 JS 및 이미지 페이로드가 문서화된 예산 내에 있습니다.
• 커머스가 있는 경우 서버 소유 가격, 서버 측 확인 및 보호된 다운로드를 사용합니다.
• 미리보기 및 프로덕션 증거가 별도로 기록됩니다.