{"id":28754635,"url":"https://github.com/vivek8968/shraddheyfrontend","last_synced_at":"2026-04-09T21:55:34.482Z","repository":{"id":299421987,"uuid":"1002981380","full_name":"Vivek8968/shraddheyfrontend","owner":"Vivek8968","description":"Production-ready React TypeScript frontend for HyperLocal Marketplace - Complete PWA with role-based authentication, geolocation, and mobile-first design","archived":false,"fork":false,"pushed_at":"2025-06-16T12:59:40.000Z","size":240,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-16T13:57:31.862Z","etag":null,"topics":["authentication","frontend","geolocation","hyperlocal","marketplace","mobile-first","pwa","react","tailwindcss","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Vivek8968.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-16T12:47:42.000Z","updated_at":"2025-06-16T12:59:43.000Z","dependencies_parsed_at":"2025-06-16T14:07:46.563Z","dependency_job_id":null,"html_url":"https://github.com/Vivek8968/shraddheyfrontend","commit_stats":null,"previous_names":["vivek8968/shraddheyfrontend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Vivek8968/shraddheyfrontend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vivek8968%2Fshraddheyfrontend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vivek8968%2Fshraddheyfrontend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vivek8968%2Fshraddheyfrontend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vivek8968%2Fshraddheyfrontend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Vivek8968","download_url":"https://codeload.github.com/Vivek8968/shraddheyfrontend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Vivek8968%2Fshraddheyfrontend/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260269459,"owners_count":22983649,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","frontend","geolocation","hyperlocal","marketplace","mobile-first","pwa","react","tailwindcss","typescript"],"created_at":"2025-06-17T01:11:13.903Z","updated_at":"2025-10-04T02:03:17.215Z","avatar_url":"https://github.com/Vivek8968.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperLocal Marketplace Frontend\n\nA 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.\n\n## 🚀 Features\n\n### Core Features\n- **Role-based Authentication**: Customer, Seller, and Admin roles with Firebase integration\n- **Geolocation Integration**: Find shops and products based on user location\n- **Progressive Web App (PWA)**: Installable, offline-capable, mobile-optimized\n- **Responsive Design**: Mobile-first approach with Tailwind CSS\n- **Real-time Updates**: React Query for efficient data fetching and caching\n\n### Customer Features\n- Discover nearby shops based on location\n- Search shops and products\n- View shop details and product inventory\n- Distance-based shop filtering\n- Mobile-optimized browsing experience\n\n### Seller Features\n- Comprehensive dashboard with analytics\n- Shop management and setup\n- Product inventory management\n- Image upload for shop and products\n- Sales analytics and insights\n\n### Admin Features\n- System-wide dashboard and analytics\n- User management (customers and sellers)\n- Shop and product moderation\n- System monitoring and logs\n\n## 🛠 Tech Stack\n\n### Core Technologies\n- **React 18** with TypeScript\n- **React Router v6** for navigation\n- **Tailwind CSS** for styling\n- **React Query** for state management and API calls\n- **Axios** for HTTP requests\n\n### Development Tools\n- **ESLint** and **Prettier** for code quality\n- **TypeScript** with strict mode\n- **PWA** capabilities with service workers\n\n### Architecture\n- **Feature-based folder structure** for scalability\n- **Centralized API layer** with error handling\n- **Context-based authentication** management\n- **Custom hooks** for reusable logic\n- **Component composition** patterns\n\n## 📁 Project Structure\n\n```\nsrc/\n├── components/           # Reusable UI components\n│   ├── common/          # Common components (LoadingSpinner, ErrorBoundary, etc.)\n│   └── ui/              # UI library components\n├── contexts/            # React contexts (Auth, Theme, etc.)\n├── features/            # Feature-based modules\n│   ├── auth/           # Authentication features\n│   ├── customer/       # Customer-specific features\n│   ├── seller/         # Seller-specific features\n│   └── admin/          # Admin-specific features\n├── hooks/              # Custom React hooks\n├── layouts/            # Layout components\n├── services/           # API services and external integrations\n├── types/              # TypeScript type definitions\n├── utils/              # Utility functions and helpers\n└── App.tsx             # Main application component\n```\n\n## 🚦 Getting Started\n\n### Prerequisites\n- Node.js 16+ and npm/yarn\n- **Backend services running** (see [backend repository](https://github.com/Vivek8968/hyperlocalbymanus))\n- Firebase project (for authentication - optional for development)\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/Vivek8968/shraddheyfrontend.git\n   cd shraddheyfrontend\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Backend Setup (Required First)**\n   ```bash\n   # Clone and set up the backend services\n   git clone https://github.com/Vivek8968/hyperlocalbymanus.git\n   cd hyperlocalbymanus\n   \n   # Install Python dependencies\n   pip install -r requirements.txt\n   \n   # Start all backend services (ports 8001-8005)\n   python run_service.py user_service \u0026\n   python run_service.py seller_service \u0026\n   python run_service.py customer_service \u0026\n   python run_service.py catalog_service \u0026\n   python run_service.py admin_service \u0026\n   ```\n\n4. **Environment Configuration**\n   ```bash\n   # The .env file is already configured for local development\n   # Backend services should be running on localhost:8001-8005\n   # See ENVIRONMENT_SETUP.md for detailed configuration\n   ```\n\n5. **Start development server**\n   ```bash\n   cd shraddheyfrontend\n   npm start\n   ```\n\n6. **Access the application**\n   - Frontend: http://localhost:12000\n   - Backend Health Check: http://localhost:8001/health\n\n### 🔧 Environment Setup\nFor detailed environment configuration, backend connection setup, and troubleshooting, see [ENVIRONMENT_SETUP.md](./ENVIRONMENT_SETUP.md).\n\n### Environment Variables\n\nCreate a `.env.development` file with the following variables:\n\n```env\n# API Configuration\nREACT_APP_USER_SERVICE_URL=http://localhost:8001\nREACT_APP_SELLER_SERVICE_URL=http://localhost:8002\nREACT_APP_CUSTOMER_SERVICE_URL=http://localhost:8003\nREACT_APP_CATALOG_SERVICE_URL=http://localhost:8004\nREACT_APP_ADMIN_SERVICE_URL=http://localhost:8005\n\n# Firebase Configuration\nREACT_APP_FIREBASE_API_KEY=your_api_key\nREACT_APP_FIREBASE_AUTH_DOMAIN=your_domain\nREACT_APP_FIREBASE_PROJECT_ID=your_project_id\n# ... other Firebase config\n```\n\n## 🔐 Authentication\n\nThe application uses Firebase Authentication with the following flow:\n\n1. **Login/Register**: Users authenticate via Firebase (OTP, Google, Apple)\n2. **Token Exchange**: Firebase token is exchanged for JWT from backend\n3. **Role-based Access**: Routes and features are protected based on user roles\n4. **Persistent Sessions**: Tokens are stored securely in localStorage\n\n### Demo Mode\nFor development/demo purposes, the app includes mock authentication that doesn't require actual Firebase setup.\n\n## 🗺 Geolocation Features\n\n### Location Services\n- **Automatic Detection**: Requests user location on app load\n- **Permission Handling**: Graceful handling of location permissions\n- **Fallback Options**: Manual location entry if geolocation fails\n- **Distance Calculation**: Haversine formula for accurate distance calculations\n\n### Privacy \u0026 Security\n- Location data is stored locally only\n- Users can opt-out of location services\n- No location tracking or persistent storage on servers\n\n## 📱 PWA Features\n\n### Installation\n- **Add to Home Screen**: Users can install the app on mobile devices\n- **Standalone Mode**: Runs like a native app when installed\n- **Custom Icons**: Branded app icons for different screen sizes\n\n### Offline Capabilities\n- **Service Worker**: Caches essential resources for offline use\n- **Offline Fallbacks**: Graceful degradation when network is unavailable\n- **Background Sync**: Syncs data when connection is restored\n\n## 🎨 UI/UX Design\n\n### Design System\n- **Tailwind CSS**: Utility-first CSS framework\n- **Consistent Spacing**: 8px grid system\n- **Color Palette**: Primary (blue) and secondary (green) colors\n- **Typography**: Inter font family for readability\n\n### Responsive Design\n- **Mobile-first**: Designed for mobile devices first\n- **Touch-friendly**: Appropriate touch targets and gestures\n\n## 🔧 Development\n\n### Available Scripts\n\n```bash\n# Development\nnpm start              # Start development server\nnpm run build          # Build for production\nnpm test               # Run tests\n\n# Code Quality\nnpm run lint           # Run ESLint (when configured)\nnpm run format         # Format code with Prettier (when configured)\n```\n\n## 🚀 Deployment\n\n### Production Build\n\n```bash\nnpm run build\n```\n\nThis creates an optimized production build in the `build/` directory.\n\n### Deployment Options\n\n#### Static Hosting\n- **Netlify**: Automatic deployments from Git\n- **Vercel**: Zero-config deployments\n- **AWS S3 + CloudFront**: Scalable static hosting\n\n## 🔄 Mobile App Export\n\n### React Native Web\nThe codebase is structured to support React Native Web for mobile app development.\n\n### Capacitor Integration\nFor native mobile app features:\n\n```bash\n# Install Capacitor\nnpm install @capacitor/core @capacitor/cli\n\n# Initialize Capacitor\nnpx cap init\n\n# Add platforms\nnpx cap add ios\nnpx cap add android\n```\n\n## 🤝 Contributing\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make changes**: Follow coding standards and conventions\n4. **Test thoroughly**: Ensure all tests pass\n5. **Commit changes**: Use conventional commit messages\n6. **Push to branch**: `git push origin feature/amazing-feature`\n7. **Open a Pull Request**: Describe changes and testing done\n\n## 📚 API Integration\n\nThe application integrates with the HyperLocal Marketplace backend services:\n\n- **User Service** (Port 8001): Authentication and user management\n- **Seller Service** (Port 8002): Shop and inventory management\n- **Customer Service** (Port 8003): Shop discovery and browsing\n- **Catalog Service** (Port 8004): Product catalog management\n- **Admin Service** (Port 8005): Administrative operations\n\nFor backend setup and API documentation, see the [backend repository](https://github.com/Vivek8968/hyperlocalbymanus).\n\n## 🔒 Security\n\n### Authentication Security\n- **JWT Tokens**: Secure token-based authentication\n- **Token Refresh**: Automatic token refresh before expiration\n- **Route Protection**: Role-based route protection\n\n### Data Security\n- **Input Validation**: Client-side validation with server-side verification\n- **HTTPS Only**: Enforce HTTPS in production\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n## 🙏 Acknowledgments\n\n- **React Team**: For the amazing React framework\n- **Tailwind CSS**: For the utility-first CSS framework\n- **React Query**: For excellent data fetching and caching\n- **TypeScript**: For type safety and developer experience\n\n---\n\nFor more information, please refer to the [backend repository](https://github.com/Vivek8968/hyperlocalbymanus) for API documentation and setup instructions.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivek8968%2Fshraddheyfrontend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvivek8968%2Fshraddheyfrontend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivek8968%2Fshraddheyfrontend/lists"}