Convex App

Convex is a full-stack event discovery mobile application built with React Native CLI, Express, and MongoDB. The core feature of Convex is its Dynamic Category Theming, which adapts the UI based on the event category (e.g., Tech, Social, Corporate, Arts).

Features

• Full Auth Flow: JWT-based access and refresh tokens, persisted securely.
• Role-based Access: Standard users and Admin users.
• Event Discovery: Filter/search events by category with dynamic theming.
• Explore Search: Nearby event discovery using MongoDB 2dsphere with:
  • current-location lookup
  • city/location search
  • selectable radius or city-wide scope
• Notifications UX: In-app notifications with unread counts on bell icons and full-message detail modal.
• Admin Workflow: User-created events enter moderation queue (approve/reject/request-more-proof).
• Organizer Tools: RSVP join/leave, attendee verification codes, and delete-request flow for events.
• Capacity Management: Real-time event joining with capacity caps.

Technologies Used

Frontend

• React Native CLI (not Expo)
• TypeScript
• React Navigation (Bottom Tabs + Stack)
• Zustand (Global State)
• Tanstack React Query (Server Cache + optimistic UI updates)
• React Native FastImage, React Native Reanimated, FlashList
• Axios (with interceptors)

Backend

• Node.js + Express
• TypeScript
• MongoDB + Mongoose (GeoJSON)
• JWT (jsonwebtoken)
• bcryptjs
• Zod Validation

Setup Instructions

Prerequisites

• Node.js (v22.11+ recommended; frontend uses >=22.11.0)
• MongoDB connection string
• React Native environment set up for Android/iOS

Backend Setup

1. Navigate to the backend folder:

   cd backend

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env

   Crucial: Ensure you enter a valid MONGODB_URI in the .env file.
4. Start the server:

   npm run dev

5. Seed an admin user (optional):

   npm run seed:admin admin@test.com

Frontend Setup

1. Navigate to the frontend folder:

   cd frontend

2. Install dependencies:

   npm install

3. For iOS (macOS only):

   cd ios && pod install && cd ..

4. Run the Metro bundler:

   npm start

5. Run on Android or iOS:

   npm run android
   # OR
   npm run ios

Build APK (Android)

1. Set release backend URL (Vercel) for bundle-time inlining:

   export REACT_NATIVE_API_BASE_URL=https://<your-backend>.vercel.app/api

2. Build release APK:

   cd frontend
   npm run android:assemble:release

3. APK output path:

   frontend/android/app/build/outputs/apk/release/app-release.apk

Deploy Backend to Vercel

1. Set Vercel project root to backend/.
2. Add these environment variables in Vercel:
   • MONGODB_URI
   • JWT_SECRET
   • JWT_REFRESH_SECRET
   • JWT_EXPIRES_IN
   • JWT_REFRESH_EXPIRES_IN
   • CLOUDINARY_CLOUD_NAME
   • CLOUDINARY_API_KEY
   • CLOUDINARY_API_SECRET
   • NODE_ENV=production
   • CORS_ORIGINS=https://<your-frontend-origin> (use * if only mobile clients)
3. Deploy backend and verify:

   curl https://<your-backend>.vercel.app/api/health

Folder Structure

• /backend/src/features - Express domain-driven routes, controllers, and services.
• /backend/src/shared - Middlewares, config, and utilities.
• /frontend/src/features - React Native domain-driven screens and components.
• /frontend/src/shared - Reusable UI, hooks, and API clients.
• /frontend/src/navigation - React Navigation configuration.

Design Philosophy

This app adheres to high aesthetic standards. By leveraging CategoryThemeProvider, the user interface transforms seamlessly depending on what the user is browsing, eliminating the generic "cookie-cutter" app feel and leaning into specialized aesthetics.