{"id":31744793,"url":"https://github.com/farab-hussain/nathan-frontend","last_synced_at":"2025-10-09T12:18:33.440Z","repository":{"id":314001628,"uuid":"1026193862","full_name":"Farab-Hussain/Nathan-frontend","owner":"Farab-Hussain","description":"Frontend: Next.js e-commerce storefront and admin dashboard with secure auth, product catalog (with flavors), wishlist, cart, orders, and mobile-first UI.","archived":false,"fork":false,"pushed_at":"2025-10-06T14:15:30.000Z","size":37633,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T14:36:44.787Z","etag":null,"topics":["accessibility","admin-dashboard","ecommerce","gsap","lenis-scroll","lucide-react","middleware","mobile-first","nextjs","nextjs-app-router","server-side-rendering","storefront","tailwindcss","typescript","zustand"],"latest_commit_sha":null,"homepage":"https://licorice4good.com","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/Farab-Hussain.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-25T13:16:58.000Z","updated_at":"2025-10-06T14:15:33.000Z","dependencies_parsed_at":"2025-09-25T12:18:31.536Z","dependency_job_id":null,"html_url":"https://github.com/Farab-Hussain/Nathan-frontend","commit_stats":null,"previous_names":["farab-hussain/nathan-frontend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Farab-Hussain/Nathan-frontend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Farab-Hussain%2FNathan-frontend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Farab-Hussain%2FNathan-frontend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Farab-Hussain%2FNathan-frontend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Farab-Hussain%2FNathan-frontend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Farab-Hussain","download_url":"https://codeload.github.com/Farab-Hussain/Nathan-frontend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Farab-Hussain%2FNathan-frontend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001446,"owners_count":26083078,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["accessibility","admin-dashboard","ecommerce","gsap","lenis-scroll","lucide-react","middleware","mobile-first","nextjs","nextjs-app-router","server-side-rendering","storefront","tailwindcss","typescript","zustand"],"created_at":"2025-10-09T12:18:28.463Z","updated_at":"2025-10-09T12:18:33.427Z","avatar_url":"https://github.com/Farab-Hussain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nathan Frontend – Comprehensive Next.js Candy E‑commerce Storefront \u0026 Administrative Platform\n\nWelcome to the Nathan Frontend repository, the official codebase for a modern, enterprise‑grade candy e‑commerce platform. This application delivers a polished, mobile‑first shopping experience and a powerful administrative dashboard that enables efficient store operations at scale. Built on Next.js (App Router), Zustand state management, and a utility‑first CSS approach, the platform emphasizes performance, security, maintainability, and long‑term extensibility.\n\n---\n\n## Table of Contents\n\n- Overview \u0026 Vision\n- Core Features\n- Architecture \u0026 Technology Stack\n- Project Structure\n- Data \u0026 API Integration\n- Authentication \u0026 Authorization\n- Admin Dashboard (Back‑Office)\n- State Management (Zustand)\n- Styling, UX, and Accessibility\n- Environment \u0026 Configuration\n- Local Development\n- Production Build \u0026 Deployment\n- Reverse Proxy \u0026 API Proxying\n- Images, Assets, and Uploads\n- Observability \u0026 Error Handling\n- Security Best Practices\n- Performance Optimizations\n- SEO \u0026 Marketing\n- Internationalization \u0026 Localization (Roadmap)\n- Affiliate System (Roadmap)\n- Mobile Application (Roadmap)\n- Testing Strategy (Roadmap)\n- Troubleshooting \u0026 FAQ\n- Contributing Guidelines\n- License\n\n---\n\n## Overview \u0026 Vision\n\nNathan Frontend provides:\n\n- A user‑centric, conversion‑focused storefront that showcases candy products, including flavor compositions and curated \"3‑pack\" bundles.\n- A robust admin area for product management (with images and flavors), stock visibility, and efficient order oversight.\n- A foundation for future growth including a full affiliate program and companion mobile apps.\n\nBusiness vision:\n\n- Enable rapid product iteration and launches (e.g., seasonal flavors, bundles).\n- Provide an exceptional mobile experience to meet modern shopping behavior.\n- Offer clean integrations with third‑party services (payments, analytics, communications).\n\n---\n\n## Core Features\n\n### User‑facing Features:\n\n- **Product Catalog**: Comprehensive product browsing with flavor metadata and stock indicators\n- **Product Detail Pages**: Rich content with images, descriptions, and interactive elements\n- **Custom Pack Builder**: Interactive 3-pack creation tool allowing users to select exactly 3 flavors\n- **Wishlist \u0026 Cart**: Persistent state with backend synchronization\n- **Order Management**: Complete order history with payment status tracking\n- **Stripe Payment Integration**: Secure checkout with success/failure handling and retry functionality\n- **Responsive Design**: Mobile-first approach with seamless desktop experience\n\n### Admin Dashboard Features:\n\n- **Product Management**: Full CRUD operations with server‑side pagination and image upload\n- **Flavor Management**: Complete flavor lifecycle with image uploads and bulk operations\n- **Inventory Management**: Real-time stock tracking with low-stock alerts and bulk updates\n- **Order Management**: Advanced filtering, sorting, search, and bulk operations\n- **Analytics Dashboard**: Real-time metrics for high-volume traffic monitoring\n- **Automated Order Verification**: AI-powered risk scoring and fraud detection\n- **Category Management**: Dynamic category creation and management\n- **System Configuration**: Centralized system settings and configuration\n\n### Platform Features:\n\n- **Authentication**: Secure cookie-based auth with middleware protection\n- **Accessibility**: WCAG-compliant components with proper ARIA attributes\n- **Performance**: Optimized images, lazy loading, and efficient state management\n- **Error Handling**: Comprehensive error boundaries and user-friendly error messages\n\n---\n\n## Architecture \u0026 Technology Stack\n\n- **Framework**: Next.js 15.5.3 (App Router)\n- **Language**: TypeScript with strict type checking\n- **State Management**: Zustand for cart, orders, wishlist, and user state\n- **Styling**: Tailwind CSS with utility-first approach\n- **Authentication**: HTTP-only cookie flow with middleware enforcement\n- **Payments**: Stripe integration with webhook handling\n- **Images**: Next.js Image component with optimized remote patterns\n\n---\n\n## Project Structure\n\n```\napp/\n  (root)/              # main storefront routes (home, shop, products, profile, cart)\n  auth/                # login, register, forgot password, reset password\n  dashboard/           # administrative pages (orders, products, analytics)\ncomponents/\n  custom/              # shared custom UI elements\n  shared/              # shared layout/header/footer\n  ui/                  # specialized UI components (FlavorCard, CustomPackBuilder)\nconstant/              # global constants and utilities\nhooks/                 # custom hooks (useUser, useAuth)\npublic/                # static assets (favicon, icons, images)\nstore/                 # Zustand stores (cart, orders, wishlist, user)\nstyles/                # global styles and Tailwind configuration\n```\n\n---\n\n## Data \u0026 API Integration\n\n- **Primary API**: Configured via `NEXT_PUBLIC_API_URL` environment variable\n- **Proxy Routes**: Next.js rewrites for seamless API integration\n- **Pagination**: Server-side pagination for scalable data handling\n- **Image Handling**: Optimized image serving with cache busting\n- **Real-time Updates**: WebSocket-ready architecture for live data\n\n### API Endpoints Integration:\n\n- **Products**: `/products/*` - Product catalog and management\n- **Orders**: `/orders/*` - Order creation, tracking, and management\n- **Payments**: `/payments/*` - Stripe integration and webhook handling\n- **Admin**: `/admin/*` - Administrative operations\n- **Analytics**: `/analytics/*` - Real-time metrics and reporting\n\n---\n\n## Authentication \u0026 Authorization\n\n- **Cookie-based Auth**: Secure HTTP-only cookies for session management\n- **Middleware Protection**: Automatic route protection and redirection\n- **Role-based Access**: User and admin role separation\n- **Session Management**: Automatic token refresh and session persistence\n\n### Security Features:\n\n- **HTTPS Enforcement**: Required for production deployments\n- **CORS Configuration**: Strict origin validation\n- **Input Validation**: Client-side validation with server-side verification\n- **XSS Protection**: Sanitized inputs and secure rendering\n\n---\n\n## Admin Dashboard (Back‑Office)\n\n### Product Management:\n\n- **CRUD Operations**: Create, read, update, delete products with validation\n- **Image Upload**: Drag-and-drop image upload with preview and validation\n- **Flavor Integration**: Product-flavor relationship management\n- **Bulk Operations**: Mass updates and batch processing\n- **Search \u0026 Filter**: Advanced filtering by category, status, and custom criteria\n\n### Inventory Management:\n\n- **Real-time Stock**: Live inventory tracking with automatic updates\n- **Low Stock Alerts**: Automated alerts for inventory management\n- **Bulk Updates**: Mass inventory adjustments with validation\n- **Stock History**: Track inventory changes over time\n\n### Order Management:\n\n- **Advanced Filtering**: Filter by status, payment status, date range, and amount\n- **Bulk Operations**: Mass status updates and batch processing\n- **Search Functionality**: Full-text search across orders\n- **Export Capabilities**: Data export for external analysis\n\n### Analytics Dashboard:\n\n- **Real-time Metrics**: Live order tracking and revenue monitoring\n- **Risk Analytics**: Automated fraud detection and risk scoring\n- **Performance Metrics**: Conversion rates, AOV, and traffic analysis\n- **Hourly Reports**: Time-based performance analysis\n\n---\n\n## State Management (Zustand)\n\n### Store Architecture:\n\n- **cartStore.ts**: Persistent cart with backend synchronization\n- **ordersStore.ts**: Order management with status tracking\n- **wishlistStore.ts**: Lightweight wishlist with persistence\n- **userStore.ts**: User authentication and profile management\n\n### Features:\n\n- **Persistence**: Automatic state persistence across sessions\n- **Optimistic Updates**: Immediate UI updates with rollback capability\n- **Error Handling**: Comprehensive error states and recovery\n- **Type Safety**: Full TypeScript integration with type-safe operations\n\n---\n\n## Styling, UX, and Accessibility\n\n### Design System:\n\n- **Mobile-first**: Responsive design optimized for mobile devices\n- **Consistent Spacing**: Standardized spacing and typography scales\n- **Color Semantics**: Meaningful color usage for status and actions\n- **Interactive States**: Clear hover, focus, and active states\n\n### Accessibility Features:\n\n- **ARIA Attributes**: Proper labeling and descriptions\n- **Keyboard Navigation**: Full keyboard accessibility\n- **Screen Reader Support**: Semantic HTML and proper structure\n- **Focus Management**: Logical focus flow and visible indicators\n\n---\n\n## Environment \u0026 Configuration\n\n### Required Environment Variables:\n\n```env\n# Backend API configuration\nNEXT_PUBLIC_API_URL=https://api.example.com\n\n# Optional configurations\nNEXT_PUBLIC_POST_AUTH_REDIRECT_URL=/\nNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...\n```\n\n### Configuration Notes:\n\n- Use full origin (scheme + host, no trailing slash)\n- Development: `http://localhost:4000`\n- Production: `https://api.licorice4good.com`\n\n---\n\n## Local Development\n\n### Prerequisites:\n\n- Node.js 18+\n- npm or yarn package manager\n\n### Setup:\n\n```bash\n# Install dependencies\nnpm ci\n\n# Start development server\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Start production server\nnpm run start\n```\n\n### Development Features:\n\n- **Hot Reload**: Instant updates during development\n- **Type Checking**: Real-time TypeScript validation\n- **Error Overlay**: Detailed error information in browser\n- **Performance Monitoring**: Built-in performance metrics\n\n---\n\n## Production Build \u0026 Deployment\n\n### Build Process:\n\n```bash\n# Clean install\nnpm ci\n\n# Production build\nnpm run build\n\n# Start production server\nnpm run start\n```\n\n### Deployment Considerations:\n\n- **Reverse Proxy**: Use Nginx or similar for TLS and compression\n- **Environment Variables**: Ensure all required variables are set\n- **Static Assets**: Configure CDN for optimal performance\n- **Monitoring**: Set up error tracking and performance monitoring\n\n---\n\n## Reverse Proxy \u0026 API Proxying\n\n### Proxy Configuration:\n\n- **Automatic Rewrites**: Configured based on `NEXT_PUBLIC_API_URL`\n- **Route Mapping**: `/auth/*`, `/api/products*`, `/cart*`, `/orders*`, `/uploads/*`\n- **Cookie Handling**: Same-origin cookies for security\n\n### Best Practices:\n\n- Prefer same-origin API (`/api`) to simplify cookie handling\n- Use HTTPS in production for secure cookie transmission\n- Configure proper CORS headers for cross-origin requests\n\n---\n\n## Images, Assets, and Uploads\n\n### Image Handling:\n\n- **Next.js Image**: Optimized image loading with lazy loading\n- **Remote Patterns**: Configured for backend image serving\n- **Cache Busting**: Automatic cache invalidation for updated images\n- **Responsive Images**: Multiple sizes for different screen densities\n\n### Asset Management:\n\n- **Static Assets**: Served from `public/` directory\n- **Favicon**: Configured in `app/layout.tsx`\n- **Icons**: SVG icons with proper accessibility attributes\n\n---\n\n## Observability \u0026 Error Handling\n\n### Error Management:\n\n- **Error Boundaries**: React error boundaries for graceful failures\n- **User-friendly Messages**: Clear error messages for users\n- **Logging**: Comprehensive error logging for debugging\n- **Recovery**: Automatic retry mechanisms for failed operations\n\n### Monitoring Recommendations:\n\n- **Error Tracking**: Integrate Sentry or similar service\n- **Performance Monitoring**: Use Vercel Analytics or similar\n- **User Analytics**: Implement privacy-compliant analytics\n\n---\n\n## Security Best Practices\n\n### Implementation:\n\n- **HTTPS Enforcement**: Required for production deployments\n- **Secure Cookies**: HTTP-only, secure, same-site cookies\n- **Input Validation**: Client and server-side validation\n- **XSS Protection**: Sanitized inputs and secure rendering\n\n### Headers Configuration:\n\n- **Content Security Policy**: Prevent XSS attacks\n- **X-Frame-Options**: Prevent clickjacking\n- **HSTS**: HTTP Strict Transport Security\n\n---\n\n## Performance Optimizations\n\n### Frontend Optimizations:\n\n- **Code Splitting**: Automatic route-based code splitting\n- **Image Optimization**: Next.js Image with WebP support\n- **Lazy Loading**: Components and images loaded on demand\n- **Caching**: Aggressive caching strategies for static assets\n\n### Backend Optimizations:\n\n- **Server-side Pagination**: Efficient data loading\n- **Database Indexing**: Optimized queries with proper indices\n- **CDN Integration**: Global content delivery\n- **Compression**: Gzip/Brotli compression for assets\n\n---\n\n## SEO \u0026 Marketing\n\n### SEO Features:\n\n- **Metadata**: Dynamic meta tags for products and pages\n- **Structured Data**: JSON-LD for rich snippets\n- **Sitemap**: Automatic sitemap generation\n- **Robots.txt**: Search engine crawling instructions\n\n### Marketing Integration:\n\n- **Analytics**: Google Analytics integration ready\n- **Social Sharing**: Open Graph and Twitter Card support\n- **Email Marketing**: Integration points for email campaigns\n\n---\n\n## Recent Updates \u0026 New Features\n\n### Version 2.0 Features (Latest):\n\n- **Custom Pack Builder**: Interactive 3-pack creation tool\n- **Stripe Payment Integration**: Complete payment processing with webhooks\n- **Advanced Admin Dashboard**: Enhanced product and order management\n- **Real-time Analytics**: Live metrics and performance monitoring\n- **Automated Order Verification**: AI-powered fraud detection\n- **Bulk Operations**: Mass updates for products, orders, and inventory\n- **Image Management**: Advanced image upload and management system\n- **Enhanced Error Handling**: Comprehensive error boundaries and recovery\n- **Performance Optimizations**: Improved loading times and user experience\n- **Accessibility Improvements**: WCAG 2.1 AA compliance\n\n### Technical Improvements:\n\n- **TypeScript Strict Mode**: Enhanced type safety\n- **Code Refactoring**: Reduced cognitive complexity\n- **Component Optimization**: Better performance and maintainability\n- **State Management**: Improved Zustand store architecture\n- **Build Optimization**: SWC integration for faster builds\n\n---\n\n## Internationalization \u0026 Localization (Roadmap)\n\n- i18n scaffolding for multi‑language storefront\n- Currency/locale formatting\n- RTL language support\n\n---\n\n## Affiliate System (Roadmap)\n\n- Affiliate login and dashboards\n- Link generator, campaign attribution, and commission reporting\n- Exportable statements and payout tracking\n\n---\n\n## Mobile Application (Roadmap)\n\n- React Native application sharing the same auth and API\n- Deep linking into product, cart, and orders\n- Push notifications for order updates and promotions\n\n---\n\n## Testing Strategy (Roadmap)\n\n- Component unit tests (Jest/RTL)\n- API contract tests for critical endpoints\n- E2E flows (Playwright) for login, add to cart, and checkout\n\n---\n\n## Troubleshooting \u0026 FAQ\n\n### Common Issues:\n\n- **\"Destination undefined\" on build**: Ensure `NEXT_PUBLIC_API_URL` is set\n- **Auth flicker on auth pages**: Middleware enforces server‑side redirect\n- **Product images not loading**: Check backend static `/uploads` mapping and Next Image remote patterns\n- **Payment failures**: Verify Stripe webhook configuration and environment variables\n- **Build errors**: Clear `.swc` cache and rebuild\n\n### Debug Steps:\n\n1. Check browser console for errors\n2. Verify environment variables\n3. Check network requests in DevTools\n4. Clear browser cache and cookies\n5. Restart development server\n\n---\n\n## Contributing Guidelines\n\n- Use feature branches and meaningful commit messages\n- Keep components small and accessible; colocate tests near code\n- Submit PRs with screenshots for UI changes\n- Follow TypeScript strict mode guidelines\n- Ensure accessibility compliance\n\n## License\n\n- Proprietary / All rights reserved (update if open‑sourcing)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarab-hussain%2Fnathan-frontend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffarab-hussain%2Fnathan-frontend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarab-hussain%2Fnathan-frontend/lists"}