프로젝트 구조

설치 및 설정

모든 단계 전에 시작하기 전에와 터미널 기본을 읽으십시오. package.json이 들어 있는 폴더인 루트에서 supastack 폴더를 엽니다. Mobile 체크아웃에는 apps/mobile과 아래 공유 패키지가 있고, All Platforms 모노레포는 Web 백엔드와 Desktop 셸을 추가합니다. 환경 변수는 로컬 .env 파일 또는 호스팅 대시보드에 저장된 이름 있는 설정입니다. 변경 후 앱을 다시 시작하고 서버 비밀을 EXPO_PUBLIC_ 값에 넣지 마십시오.

1. 편집기에서 apps/mobile/app/_layout.tsx를 엽니다 — 모든 화면이 공유하는 루트 레이아웃입니다.

2. apps/mobile/src/를 둘러봅니다 — 기능 영역당 하나의 폴더이며 각각 로직과 테스트를 담고 있습니다.

3. 리포지토리 루트에서 corepack pnpm --filter @supastack/mobile start를 실행하고 기기에서 미리 보기를 엽니다.

Expo 앱은 기능 모듈을 호출하는 라우트로 구성됩니다. 라우트는 얇게 유지됩니다 — 화면을 렌더링할 뿐이며, 호출하는 로직은 src/ 아래에 테스트와 함께 있습니다. 동작을 변경하기 전에 AGENTS.md와 .ai/PROJECT_CONTEXT.md를 읽으십시오. .ai/ 미러 문서는 파일만으로는 보이지 않는 결정을 기록합니다.

apps/mobile/app/          Expo Router routes — sign-in, onboarding, invite, paywall
apps/mobile/app/(app)/    Signed-in screens — home, chat, notifications, settings, content, commerce, assistant
apps/mobile/src/          Feature modules — auth, api, purchases, offline, push, ui, theme, i18n
packages/ui-native/       Shared native view-models
packages/design-tokens/   Shared theme tokens
apps/mobile/app.config.ts Scheme and allowed-origin derivation
apps/mobile/eas.json      EAS build and submit profiles
docs/                     Runbooks incl. store submission
.agents/skills/           Task guides for coding agents

변경이 속할 위치

편집 전에 어떤 폴더가 변경을 소유하는지 결정하십시오. 경험 법칙: 라우트 파일은 렌더링만 하고, 재사용 가능한 로직은 src/ 모듈에 있으며, 서버가 결정해야 하는 것은 앱에 들어가지 않습니다.

• 첫 번째 모바일 기능 구축

• 새 로그인 화면 → 라우트는 apps/mobile/app/(app)/, 로직은 apps/mobile/src/<feature>/.
• 새 인증 전 또는 독립형 화면 → (app) 그룹 밖의 apps/mobile/app/.
• 백엔드 호출 → apps/mobile/src/api/client.ts — 임시로 fetch하는 대신 형식화된 클라이언트를 확장합니다.
• 화면 간 공유 비주얼 → apps/mobile/src/ui/ 프리미티브; 크로스 플랫폼 뷰 모델 → packages/ui-native/.
• 색상, 간격, 다크/라이트 값 → packages/design-tokens/가 뒷받침하는 apps/mobile/src/theme/.
• 새 번역 키 → apps/mobile/src/i18n/ 아래의 네 개 카탈로그 모두.
• 서버 측 모든 것 — 데이터, 권한, 공급자 호출 → Web 백엔드 리포지토리. Mobile 전용 구매에서는 별도의 체크아웃입니다.

구현 워크플로

라우트 파일에서 시작해 렌더링하는 기능 모듈, 그다음 API 클라이언트 호출을 따라가십시오 — 서버가 소유권을 결정하며 앱은 절대 다시 유도하지 않습니다. .agents/skills/의 add-a-mobile-screen 스킬이 같은 순서를 안내합니다.

공유 패키지 또는 API 클라이언트를 편집한 후 패키지 테스트와 타입 검사를 실행합니다. 클라이언트는 백엔드가 제공하는 것과 동일한 계약을 유지해야 합니다.

검증 및 문제 해결

expo start가 누락된 모듈을 보고하면 리포지토리 루트에서 설치 명령을 실행하십시오 — 앱 폴더만으로는 워크스페이스 패키지를 확인할 수 없습니다. 화면이 스타일 없이 나타나면 하드코딩된 색상의 원시 요소 대신 src/ui 프리미티브를 구성했는지 확인하십시오.

corepack pnpm --filter @supastack/mobile test
corepack pnpm --filter @supastack/mobile typecheck