circle-collect/README.md

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 (Android Studio / Xcode)
• Firebase configuration files in place (android/app/google-services.json, iOS GoogleService-Info.plist) for push notifications

Install dependencies

npm install

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

bundle install
bundle exec pod install

Run the app

Start Metro:

npm start

Then in a separate terminal:

# 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. If Android builds fail after dependency changes, try cd android && ./gradlew clean.