viberoom-web/docs/skills/frontend_architecture.md

VibeRoom 프론트엔드 아키텍처 규칙 (Lite FSD)

본 문서는 VibeRoom 웹앱의 프론트엔드 코드 작성을 위한 핵심 지침서입니다. AI(Cursor, Cline, Gemini 등)를 통한 코딩 시 반드시 본 문서의 아키텍처 원칙을 준수해야 코드가 얽히고 망가지는(Code Rot) 현상을 방지할 수 있습니다.

1. 아키텍처 핵심 사상

이 프로젝트는 **'도메인/피처 기반(Feature-Driven) 아키텍처'**를 채택했습니다. 복잡한 FSD(Feature-Sliced Design)를 단순화하여 백엔드 개발자와 AI가 모두 이해하기 쉬운 구조입니다.

핵심 철학: "한 기능(Domain)에 관련된 코드는 무조건 하나의 features 폴더에 모아둔다."

2. 폴더 구조 설명 및 엄수 사항

src/
├── app/                  # 진입점 (Routing & Pages)
├── features/             # 도메인 로직 묶음 (비즈니스 핵심)
├── shared/               # 공통 요소 (UI, Lib, Type - 도메인 종속성 0%)
└── store/                # 글로벌 상태 관리 (최소한으로 사용)

🚨 [규칙 1] app/ 폴더는 멍청한 조립 공장이다.

• app/**/page.tsx 파일에는 절대 복잡한 비즈니스 로직(API 호출, 상태 관리)을 길게 작성하지 마세요.
• 오직 features/나 shared/에서 완성된 컴포넌트들을 import 해와서 배치(Layout)하는 역할만 수행합니다.
• 데이터 패칭이 필요하다면 SSR/RSC(React Server Components)의 장점을 살려 데이터를 가져온 후 하위 컴포넌트에 넘겨주는 선까지만 작성합니다.

🚨 [규칙 2] features/ 간의 상호 참조를 절대 금지한다.

• src/features/timer 내부의 파일이 src/features/space 내부의 파일을 직접 import 해서는 안 됩니다.
• 기능(도메인) 간의 결합도가 높아지면, AI가 한 도메인을 수정할 때 다른 도메인이 망가지는 나비효과가 발생합니다.
• 만약 두 기능이 서로 통신해야 한다면 1) 부모 페이지 컴포넌트(app/)에서 상태를 내려주거나 2) store/의 전역 상태를 활용하세요.

🚨 [규칙 3] shared/는 도메인을 몰라야 한다.

• src/shared/ui/Button.tsx는 자기가 '로그인 버튼'인지, '타이머 시작 버튼'인지 절대 알면 안 됩니다.
• 오직 범용적인 디자인 컴포넌트, 유틸 함수, 전역 타입만 위치합니다.
• 이 폴더 안의 코드는 어떤 프로젝트에 복사/붙여넣기 해도 바로 동작할 만큼 순수(Pure)해야 합니다.

🚨 [규칙 4] 컴포넌트 작성 시 '기능 중심' 사고방식

• "버튼 하나 만들자" ➡️ shared/ui에 생성.
• "로그인 폼 만들자" ➡️ features/auth/components에 생성.
• "타이머 시작 함수 만들자" ➡️ features/timer/api 또는 hooks에 생성.
• "사용자 데이터를 여러 화면에서 공유하자" ➡️ store/globalStore.ts (Zustand) 생성.

---

※ AI 에이전트 지시사항 ※ 코드를 생성하거나 리팩토링할 때 위 4가지 규칙 중 하나라도 위반하는 제안을 해서는 안 됩니다. 새로운 파일을 생성할 때는 반드시 이 폴더 트리 구조 중 어디에 속해야 하는지 명확히 설명하고 승인을 받으세요.