# Wifaq

**Gerez vos finances en couple, equitablement.**

Wifaq is a mobile fintech application for equitable household financial management between couples. It calculates a "Quotient Equitable" that factors in both monetary income and domestic labor to suggest fair expense distribution.

Built for the Centre Communautaire Musulman de Quebec (CCMQ).

## Tech Stack

- **Framework:** React Native + Expo SDK 55 (TypeScript strict)
- **Navigation:** React Navigation 7 (Stack + Bottom Tabs)
- **State:** Zustand
- **Storage:** expo-sqlite (local-first, no cloud)
- **Forms:** react-hook-form + zod
- **Animations:** react-native-reanimated 3
- **i18n:** Custom (FR/EN/AR + RTL)

## Getting Started

### Prerequisites

- Node.js >= 18
- npm or yarn
- Expo CLI: `npx expo`
- iOS Simulator (macOS) or Android Emulator

### Installation

```bash
cd wifaq
npm install
```

### Running

```bash
# Start Expo dev server
npx expo start

# iOS Simulator
npx expo start --ios

# Android Emulator
npx expo start --android
```

### Testing

```bash
npm test
npm run test:watch
```

### Type Checking

```bash
npm run lint
```

## Project Structure

```
src/
  components/
    ui/           # Button, Card, Input, Typography, Badge, Stepper, etc.
    layout/       # SafeScreen, Header
  db/
    repositories/ # expenseRepository, equityRepository, settingsRepository
    schema.ts     # SQL CREATE TABLE statements
    database.ts   # SQLite initialization
  hooks/          # useReduceMotion
  i18n/
    locales/      # fr.ts, en.ts, ar.ts
    index.ts      # t(), setLocale(), getLocale()
  navigation/     # AppNavigator (Stack + Tabs)
  screens/
    onboarding/   # Splash, Welcome, Language
    auth/         # AuthScreen
    quiz/         # QuizContainer, Steps 1-6
    app/          # Dashboard, Budget, AddExpense, CommonPot
    plus/         # PlusHub, Equity, ComingSoon
    system/       # Settings, Privacy, Help, Notifications
  store/          # useAppStore, useQuizStore, useExpenseStore
  theme/          # tokens.ts (design tokens)
  types/          # TypeScript interfaces
  utils/          # equityCalculator, format
docs/
  BRAND.md        # Brand style guide
  DECISIONS.md    # Architectural decisions
```

## Core Feature: Quotient Equitable

The equity calculator determines fair expense distribution:

1. **Income ratio:** Each partner's share of total household income
2. **Domestic work adjustment:** Hours of domestic labor monetized at configurable rate ($18/hr default)
3. **Adjusted ratio:** Income minus domestic labor value gives adjusted contributions

Formula: `adjusted_income = income - (domestic_hours x hourly_rate x 4.33)`

## App Flow

1. **Splash** - Animated logo
2. **Welcome** - 3-slide feature carousel
3. **Language** - FR / EN / AR selection
4. **Auth** - Local profile creation
5. **Quiz** (6 steps):
   - Household profile
   - Income declaration
   - Monthly charges
   - Domestic work hours
   - Equity result
   - Completion
6. **Main App** - Bottom tabs (Dashboard, Budget, +Expense, Pot Commun, Plus)

## QA Checklist

- [ ] All screens render without crashes
- [ ] French translations complete and accurate
- [ ] English translations complete
- [ ] Arabic translations display correctly with RTL layout
- [ ] RTL layout mirrors properly (text alignment, icon positions)
- [ ] Equity calculator produces correct ratios
- [ ] Expense add/delete flow works end-to-end
- [ ] Navigation flow: splash -> welcome -> language -> auth -> quiz -> app
- [ ] Bottom tab navigation switches correctly
- [ ] Animations respect reduce motion preference
- [ ] Accessibility labels present on all interactive elements
- [ ] Keyboard dismisses properly on form screens
- [ ] Large text / dynamic type doesn't break layouts
- [ ] App works offline (no network dependency)

## Fonts

The app uses the Inter font family. Fonts are loaded via `expo-font` at app startup. Place font files in `assets/fonts/`:

- Inter-Regular.ttf
- Inter-Medium.ttf
- Inter-SemiBold.ttf
- Inter-Bold.ttf

Download from [Google Fonts - Inter](https://fonts.google.com/specimen/Inter).

## License

Private - CCMQ
