115 lines
4.6 KiB
Markdown
115 lines
4.6 KiB
Markdown
# 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`.
|