Your Sofia Mobile Development

AI assistant for developing the Your Sofia mobile app - a bilingual (Bulgarian/English) React Native application built with Expo for Sofia city services, news, air quality monitoring, and payments.

Project Context

You are working on a React Native mobile app for Sofia Municipality that provides city services to residents. The app is built with Expo 54, uses Payload CMS as a backend (separate repository: your-sofia-api), and supports Bulgarian (default) and English languages.

**Key Architecture:**

Core Responsibilities

1. Code Formatting

**ALWAYS read `.prettierrc` before generating code:**

Run `pnpm format` to verify formatting.

2. Internationalization (i18n)

**Bulgarian is the default language, not English.**

**CRITICAL RULES:**

**Translation Namespaces:**

**Usage:**

```typescript

const { t } = useTranslation()

const { t: t_services } = useTranslation('services')

```

Language persists in AsyncStorage (`user-language` key).

3. Routing (Expo Router)

File-based routing in `app/` directory:

4. Payload CMS Integration

**Backend must be running (your-sofia-api repository):**

**API Endpoints:**

5. Component Patterns

**Icons:**

**Modals:**

**Styling:**

**External Libraries:**

6. Development Commands

```bash

pnpm dev # Start Expo (disables telemetry)

pnpm typecheck # TypeScript checks

pnpm lint # Expo linting

pnpm format # Prettier formatting

```

7. Environment Setup

**Required `.env.local`:**

```

EXPO_PUBLIC_API_URL=http://localhost:3000

```

Step-by-Step Workflow

When Creating New Components:

1. Read `.prettierrc` to understand formatting rules

2. Check existing translations in `translations/bg.ts` and `translations/en.ts`

3. Add new translation keys to BOTH files (Bulgarian first, then English)

4. Use `useTranslation()` hook for all text

5. Follow component patterns from `components/` directory

6. Use `commonStyles` from `styles/common.ts` for consistent styling

7. Run `pnpm format` before committing

When Adding New Features:

1. Check if backend API changes needed (your-sofia-api repository)

2. Update TypeScript types in `types/` directory

3. Create reusable hooks in `hooks/` if fetching data

4. Add routing in `app/` directory following Expo Router conventions

5. Update tab navigation in `(tabs)/_layout.tsx` if needed

6. Run `pnpm typecheck` to verify types

When Working with News/Content:

1. Ensure Payload CMS backend is running (http://localhost:3000/admin)

2. Use `useNews` hook for fetching: `const { news, loading } = useNews('festivals')`

3. Image URLs are auto-prefixed with API URL

4. News state automatically updates on language change

5. Test with both Bulgarian and English locales

When Debugging:

1. Payload Admin: http://localhost:3000/admin

2. API Explorer: http://localhost:3000/api/news

3. Expo DevTools: Press `m` in terminal

4. TypeScript: `pnpm typecheck` (doesn't auto-check)

5. Check AsyncStorage for language persistence (`user-language` key)

Common Pitfalls to Avoid

1. ❌ Hardcoding text instead of using translation keys

2. ❌ Using English as default language (Bulgarian is default)

3. ❌ Starting dev without running backend (your-sofia-api)

4. ❌ Forgetting to add translation keys to both `bg.ts` AND `en.ts`

5. ❌ Using inline modals instead of extracting to components

6. ❌ Using npm/yarn instead of pnpm

7. ❌ Formatting code without reading `.prettierrc`

8. ❌ Using `localhost` instead of `127.0.0.1` for native features

9. ❌ Not checking TypeScript types with `pnpm typecheck`

10. ❌ Forgetting PostgreSQL with PostGIS must be running

Key Files Reference

Integration Points

**News API (Payload CMS):**

**Cross-Component Communication:**

**External Services:**

Important Constraints