A modern, production-ready React TypeScript frontend for the HyperLocal Marketplace platform. This application enables customers to discover nearby shops, sellers to manage their businesses, and administrators to oversee the platform.
- Role-based Authentication: Customer, Seller, and Admin roles with Firebase integration
- Geolocation Integration: Find shops and products based on user location
- Progressive Web App (PWA): Installable, offline-capable, mobile-optimized
- Responsive Design: Mobile-first approach with Tailwind CSS
- Real-time Updates: React Query for efficient data fetching and caching
- Discover nearby shops based on location
- Search shops and products
- View shop details and product inventory
- Distance-based shop filtering
- Mobile-optimized browsing experience
- Comprehensive dashboard with analytics
- Shop management and setup
- Product inventory management
- Image upload for shop and products
- Sales analytics and insights
- System-wide dashboard and analytics
- User management (customers and sellers)
- Shop and product moderation
- System monitoring and logs
- React 18 with TypeScript
- React Router v6 for navigation
- Tailwind CSS for styling
- React Query for state management and API calls
- Axios for HTTP requests
- ESLint and Prettier for code quality
- TypeScript with strict mode
- PWA capabilities with service workers
- Feature-based folder structure for scalability
- Centralized API layer with error handling
- Context-based authentication management
- Custom hooks for reusable logic
- Component composition patterns
src/
├── components/ # Reusable UI components
│ ├── common/ # Common components (LoadingSpinner, ErrorBoundary, etc.)
│ └── ui/ # UI library components
├── contexts/ # React contexts (Auth, Theme, etc.)
├── features/ # Feature-based modules
│ ├── auth/ # Authentication features
│ ├── customer/ # Customer-specific features
│ ├── seller/ # Seller-specific features
│ └── admin/ # Admin-specific features
├── hooks/ # Custom React hooks
├── layouts/ # Layout components
├── services/ # API services and external integrations
├── types/ # TypeScript type definitions
├── utils/ # Utility functions and helpers
└── App.tsx # Main application component
- Node.js 16+ and npm/yarn
- Backend services running (see backend repository)
- Firebase project (for authentication - optional for development)
-
Clone the repository
git clone https://github.com/Vivek8968/shraddheyfrontend.git cd shraddheyfrontend -
Install dependencies
npm install
-
Backend Setup (Required First)
# Clone and set up the backend services git clone https://github.com/Vivek8968/hyperlocalbymanus.git cd hyperlocalbymanus # Install Python dependencies pip install -r requirements.txt # Start all backend services (ports 8001-8005) python run_service.py user_service & python run_service.py seller_service & python run_service.py customer_service & python run_service.py catalog_service & python run_service.py admin_service &
-
Environment Configuration
# The .env file is already configured for local development # Backend services should be running on localhost:8001-8005 # See ENVIRONMENT_SETUP.md for detailed configuration
-
Start development server
cd shraddheyfrontend npm start -
Access the application
- Frontend: http://localhost:12000
- Backend Health Check: http://localhost:8001/health
For detailed environment configuration, backend connection setup, and troubleshooting, see ENVIRONMENT_SETUP.md.
Create a .env.development file with the following variables:
# API Configuration
REACT_APP_USER_SERVICE_URL=http://localhost:8001
REACT_APP_SELLER_SERVICE_URL=http://localhost:8002
REACT_APP_CUSTOMER_SERVICE_URL=http://localhost:8003
REACT_APP_CATALOG_SERVICE_URL=http://localhost:8004
REACT_APP_ADMIN_SERVICE_URL=http://localhost:8005
# Firebase Configuration
REACT_APP_FIREBASE_API_KEY=your_api_key
REACT_APP_FIREBASE_AUTH_DOMAIN=your_domain
REACT_APP_FIREBASE_PROJECT_ID=your_project_id
# ... other Firebase configThe application uses Firebase Authentication with the following flow:
- Login/Register: Users authenticate via Firebase (OTP, Google, Apple)
- Token Exchange: Firebase token is exchanged for JWT from backend
- Role-based Access: Routes and features are protected based on user roles
- Persistent Sessions: Tokens are stored securely in localStorage
For development/demo purposes, the app includes mock authentication that doesn't require actual Firebase setup.
- Automatic Detection: Requests user location on app load
- Permission Handling: Graceful handling of location permissions
- Fallback Options: Manual location entry if geolocation fails
- Distance Calculation: Haversine formula for accurate distance calculations
- Location data is stored locally only
- Users can opt-out of location services
- No location tracking or persistent storage on servers
- Add to Home Screen: Users can install the app on mobile devices
- Standalone Mode: Runs like a native app when installed
- Custom Icons: Branded app icons for different screen sizes
- Service Worker: Caches essential resources for offline use
- Offline Fallbacks: Graceful degradation when network is unavailable
- Background Sync: Syncs data when connection is restored
- Tailwind CSS: Utility-first CSS framework
- Consistent Spacing: 8px grid system
- Color Palette: Primary (blue) and secondary (green) colors
- Typography: Inter font family for readability
- Mobile-first: Designed for mobile devices first
- Touch-friendly: Appropriate touch targets and gestures
# Development
npm start # Start development server
npm run build # Build for production
npm test # Run tests
# Code Quality
npm run lint # Run ESLint (when configured)
npm run format # Format code with Prettier (when configured)npm run buildThis creates an optimized production build in the build/ directory.
- Netlify: Automatic deployments from Git
- Vercel: Zero-config deployments
- AWS S3 + CloudFront: Scalable static hosting
The codebase is structured to support React Native Web for mobile app development.
For native mobile app features:
# Install Capacitor
npm install @capacitor/core @capacitor/cli
# Initialize Capacitor
npx cap init
# Add platforms
npx cap add ios
npx cap add android- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make changes: Follow coding standards and conventions
- Test thoroughly: Ensure all tests pass
- Commit changes: Use conventional commit messages
- Push to branch:
git push origin feature/amazing-feature - Open a Pull Request: Describe changes and testing done
The application integrates with the HyperLocal Marketplace backend services:
- User Service (Port 8001): Authentication and user management
- Seller Service (Port 8002): Shop and inventory management
- Customer Service (Port 8003): Shop discovery and browsing
- Catalog Service (Port 8004): Product catalog management
- Admin Service (Port 8005): Administrative operations
For backend setup and API documentation, see the backend repository.
- JWT Tokens: Secure token-based authentication
- Token Refresh: Automatic token refresh before expiration
- Route Protection: Role-based route protection
- Input Validation: Client-side validation with server-side verification
- HTTPS Only: Enforce HTTPS in production
This project is licensed under the MIT License.
- React Team: For the amazing React framework
- Tailwind CSS: For the utility-first CSS framework
- React Query: For excellent data fetching and caching
- TypeScript: For type safety and developer experience
For more information, please refer to the backend repository for API documentation and setup instructions.