# CircleCollect

CircleCollect is a React Native mobile app for organizing and managing group fund collections (rotating savings / contribution circles). Organizers create contribution groups, members join and contribute on a cycle, and a winner can be randomly selected each cycle. Payments are handled through an in-app payment gateway, and push notifications keep members up to date.

## Features

- **OTP-based authentication** — login with a mobile number and one-time password; tokens stored securely with `react-native-keychain`
- **Organizer registration** — regular users can apply to become organizers and register bank / mobile money details
- **Group management** — create, edit, and review groups; browse public groups; approve or decline join requests; invite members from contacts
- **Contributions and payments** — contribute to one group or pay several at once (bulk pay), choose a payment mode, and complete checkout in a payment gateway WebView
- **Cycle winner selection** — randomly select a winning member for a group's current cycle
- **Transactions** — view personal transaction history and group payment records
- **Push notifications** — Firebase Cloud Messaging with Notifee for display, including deep-link redirection from a notification to the relevant screen
- **Profile** — edit profile details, profile picture, and bank details

## Tech stack

| Area | Library |
| --- | --- |
| Framework | React Native 0.81, React 19, TypeScript |
| Navigation | React Navigation (native stack + bottom tabs) with deep linking |
| State | Redux Toolkit + redux-persist (user, notifications) |
| Server state | TanStack React Query with custom CRUD hooks (`useFetch`, `useCreate`, `useUpdate`, `useDelete`) |
| Networking | Axios client with auth interceptors (`src/api/client.ts`) |
| Push notifications | `@react-native-firebase/messaging` + `@notifee/react-native` |
| Secure storage | `react-native-keychain`, AsyncStorage |
| UI | React Native Paper, RN Elements, vector icons, Reanimated, linear gradient, calendars |
| Payments | Gateway checkout via `react-native-webview` |

## Project structure

```
src/
├── api/            # Axios client with request/response interceptors
├── assets/         # Images and static assets
├── components/     # Shared UI (cards, buttons, alerts, common widgets)
├── constents/      # Font family constants
├── hooks/
│   ├── core/       # React Query CRUD hooks + API debug helpers
│   └── ui/         # useTheme
├── navigation/     # AppNavigator (root stack), BottomTabs, route types
├── payment/        # Payment WebView wrapper
├── redux/          # Store, userSlice, notificationSlice
├── screens/
│   ├── home/       # Dashboard, group lists, requests
│   ├── management/ # Group/member management, payments, winner selection
│   ├── payment/    # Payment mode selection, gateway WebView
│   ├── profile/    # Profile, become organizer, bank details
│   ├── transaction/# Transaction history
│   ├── notification/
│   └── setting/
├── theme/          # ThemeProvider and theme tokens
└── utils/          # API URLs, helpers, Firebase setup, navigation service
```

The backend base URL and all endpoints are defined in `src/utils/ApiUrls.tsx`.

## Getting started

### Prerequisites

- Node.js >= 20
- A working [React Native environment](https://reactnative.dev/docs/set-up-your-environment) (Android Studio / Xcode)
- Firebase configuration files in place (`android/app/google-services.json`, iOS `GoogleService-Info.plist`) for push notifications

### Install dependencies

```sh
npm install
```

For iOS, also install CocoaPods dependencies (first clone and after updating native deps):

```sh
bundle install
bundle exec pod install
```

### Run the app

Start Metro:

```sh
npm start
```

Then in a separate terminal:

```sh
# Android
npm run android

# iOS
npm run ios
```

## Scripts

| Command | Description |
| --- | --- |
| `npm start` | Start the Metro dev server |
| `npm run android` | Build and run on Android |
| `npm run ios` | Build and run on iOS |
| `npm test` | Run Jest tests |
| `npm run lint` | Run ESLint |

## Configuration

- **API base URL** — set in `src/utils/ApiUrls.tsx` (`BASE_URL`). A commented-out local URL is provided for development against a local backend.
- **Deep linking** — the app registers the `myapp://` scheme for notification redirection (see `src/navigation/AppNavigator.tsx`).

## Troubleshooting

See the React Native [Troubleshooting guide](https://reactnative.dev/docs/troubleshooting). If Android builds fail after dependency changes, try `cd android && ./gradlew clean`.