# Repository Guidelines

## Project Structure & Module Organization
- Entry points: `App.js`, `index.js`, `index.web.js`.
- Source code: `src/` (key folders: `actions/`, `components/`, `hooks/`, `screens/`, `providers/`, `navigation/`, `utils/`, `styles/`, `assets/`).
- Native projects: `android/`, `ios/`.
- Assets: `assets/` and `src/assets/`.
- Config: `app.json`, `eas.json`, `metro.config.js`, `config/`.
- Backend: `functions/` (Firebase Cloud Functions, Node 20).

## Build, Test, and Development Commands
- Install deps: `yarn` (preferred; lockfile is `yarn.lock`).
- Run app: `yarn start` (Expo dev client), `yarn android`, `yarn ios`, `yarn web`.
- Clean native builds: `yarn clean` (runs `expo prebuild --clean`).
- Web build: `yarn build:web` → outputs to `dist/`.
- Desktop (pake): `yarn build:desktop:dev` (requires dev server), `yarn build:desktop:prod`.
- Firebase functions: `cd functions && npm run serve` (emulators), `npm run deploy`.

## Coding Style & Naming Conventions
- Languages: React Native (JS/TS). Indentation: 2 spaces.
- Lint/format: ESLint (`expo`, `prettier`) + Prettier. Keep code formatted; fix all lint errors.
  - Example: `npx eslint src`.
- Components and screens: PascalCase filenames, e.g., `MusicDetails.js`, `CreateLyricsWithAi.js`.
- Hooks: prefix with `use` (e.g., `src/hooks/useFirestorePagination.js`).
- Utilities: lowerCamelCase modules in `src/utils/` or `helpers/`; prefer named exports.
- Avoid duplicating inline styles; share via `src/styles/`.

## Testing Guidelines
- No unit tests configured yet. If adding tests, prefer Jest + `@testing-library/react-native`.
- Place tests under `src/**/__tests__/` or as `*.test.[jt]sx` near sources.
- Until tests exist, include manual test steps in PRs (platform, device, steps, expected results).

## Commit & Pull Request Guidelines
- Commits: concise, imperative subject (≤72 chars). Optional scope, e.g., `feat(login): add Google button`.
- PRs must include: clear description, screenshots/video for UI changes, reproduction and verification steps, linked issues, and notes on breaking changes.
- Verify the app launches on Android, iOS, and Web locally; fix lint and type warnings before requesting review.

## Security & Configuration Tips
- Never commit secrets (e.g., `functions/serviceAccountKey.json`, API keys). Use Firebase/Expo secrets and environment config.
- Manage runtime config via `app.json`/`eas.json` or remote config; avoid hardcoding credentials.
- Before EAS builds, run `yarn clean` to resync native projects.