프로젝트 구조

설치 및 설정

어떤 단계를 시작하기 전에 시작하기 전에 및 터미널 기본 사항을 읽어보세요. 이 지침에서는 VS Code에서 전체 supastack 단일 저장소를 열었다고 가정합니다. 해당 루트 package.json은 저장소 루트를 표시합니다. pnpm 명령에서 작업 영역 패키지는 앱 또는 공유 코드 폴더입니다. 제품에서 작업공간은 팀의 데이터 컨테이너이자 보안 경계입니다. corepack pnpm --filter ... 명령이 해당 루트에서 실행되는 동안 monorepo에서 하나의 패키지를 선택합니다. 동기화된 모바일 또는 데스크톱 폴더만 열었다면 웹 백엔드, Docker 설정 또는 루트 스크립트가 포함되지 않습니다. 이 모노 저장소 또는 연결 가능한 호스팅 서버에서 백엔드를 실행하고 플랫폼 폴더의 자체 스크립트를 사용하세요. 환경 변수는 로컬 .env 파일이나 호스팅 대시보드에 저장된 명명된 설정입니다. 관련 앱을 변경한 후 다시 시작하고, NEXT_PUBLIC_ 및 EXPO_PUBLIC_ 값에서 서버 비밀을 유지하세요.

1. VS Code에서 루트 package.json을 연 다음 웹 사이트의 경우 apps/web, Expo의 경우 apps/mobile, 데스크톱 셸의 경우 apps/desktop, 공유 부분의 경우 패키지를 찾아보세요.

2. 저장소 루트에서 corepack pnpm --filter @supastack/web dev를 실행합니다.

3. http://localhost:3000. 열기 예상: 공유 패키지가 동일한 저장소에 남아 있는 동안 웹 앱은 apps/web에서 시작됩니다. 데스크톱 창은 두 번째 제품을 포함하지 않고 이 웹 앱을 래핑합니다.

pnpm 워크스페이스는 apps/web의 Next.js, apps/mobile의 Expo, packages 아래의 공유 패키지를 포함합니다. 워크스페이스 명령은 리포지토리 루트에서 실행합니다. 애플리케이션 라우트는 공유 모듈을 구성하고, 제품 고유 동작은 소비 제품에 속합니다.

동작을 변경하기 전에 AGENTS.md와 .ai/PROJECT_CONTEXT.md를 읽으세요. .ai/의 파일 미러는 단일 컴포넌트로는 항상 명확하지 않은 결정과 제약을 설명합니다.

apps/web/app/       Routes and layouts
apps/web/src/       Web components and server composition
apps/mobile/        Expo application
packages/           Shared contracts and adapters
tests/              Cross-module and browser checks
docs/               Operational guides

복사 명령

설명을 따라 명령이 실행되는 폴더를 확인하세요. 두 개의 터미널에 레이블이 지정되어 있으면 두 개의 터미널 창을 열고 두 번째 명령을 사용하는 동안 첫 번째 명령을 계속 실행하세요.

corepack pnpm --filter @supastack/web dev

변경이 속할 위치

편집하기 전에 어떤 앱이나 패키지가 이 변경을 소유하는지 결정하세요. 경험 법칙은 이렇습니다: 한 제품 표면만 필요로 하면 그 앱에 두고, 모든 표면이 필요로 하면 packages/ 아래의 공유 패키지에 둡니다.

웹 저장소와 All Platforms 모노레포는 아래의 모든 폴더를 포함합니다. 단독 모바일이나 데스크톱 체크아웃에는 자체 앱만 있습니다 — 서버 코드는 웹 저장소에 남아 있습니다.

• 첫 기능 만들기

• 새 마케팅이나 랜딩 페이지 → apps/web/app/ — 공개 웹사이트입니다.
• 로그인한 제품 안의 새 화면 → 경로는 apps/web/app/, 로직은 apps/web/src/ — 페이지는 공유 패키지를 조합합니다.
• 새 API 경로 → apps/web/app/api/ — 웹 앱의 서버 쪽 절반입니다.
• 모든 앱이 공유하는 변경 — 데이터베이스 테이블, 계약, 공급자 어댑터 → packages/ 안의 맞는 폴더입니다.
• 폰 전용 화면 → apps/mobile/ — 자체 백엔드를 갖는 대신 웹 앱의 API와 통신합니다.
• 데스크톱 전용 동작 → apps/desktop/ — Tauri 셸은 웹 앱을 감싸며 제품 UI를 거의 포크하지 않습니다.

구현 워크플로

사용자 액션을 소유하는 라우트에서 시작해, 그 서버 핸들러를 따라간 다음 호출하는 공유 패키지를 검사하세요. UI 컴포넌트는 워크스페이스 해석, 결제 인가, 프로바이더 선택을 재생성해서는 안 됩니다.

라우트를 추가할 때 공개인지 인증이 필요한지 결정하세요. 사용자 레코드에 닿기 전에 서버에서 인증된 소유권을 해석하고 서버 자격 증명을 클라이언트 임포트 밖에 두세요.

검증 및 문제 해결

명령이 필터와 일치하는 프로젝트가 없다고 보고하는 경우 터미널이 루트 package.json이 포함된 폴더에 있는지 확인하세요. 포트 3000이 이미 사용 중이면 먼저 다른 로컬 웹 서버를 중지하십시오. 별도의 데스크톱 채팅 또는 로그인 구현을 찾지 마십시오. 데스크톱 셸은 웹 백엔드를 로드합니다.

패키지 계약을 변경한 후 관련 테스트와 타입 검사를 실행하세요. 공유 타입을 변경할 때 웹과 모바일 소비자를 검사하세요. 성공한 웹 빌드만으로는 네이티브 앱 호환성이 확립되지 않습니다.