A modern, responsive retail management system frontend built with Next.js 16, React 19, TypeScript, and Tailwind CSS. This application provides an intuitive interface for managing inventory, sales, procurement, and analytics.
- Framework: Next.js 16 (App Router)
- UI Library: React 19
- Language: TypeScript
- Styling: Tailwind CSS 4
- State Management: Redux Toolkit (@reduxjs/toolkit)
- Form Handling: React Hook Form with Zod validation
- UI Components: Radix UI primitives
- HTTP Client: Axios
- Charts: Recharts
- Payments: Stripe (@stripe/react-stripe-js, @stripe/stripe-js)
- Icons: Lucide React
- Theme: next-themes (Dark/Light mode)
- Notifications: Sonner (Toast notifications)
- Date Utilities: date-fns
frontend/
├── src/ # Source code directory
│ ├── app/ # Next.js App Router pages
│ │ ├── layout.tsx # Root layout with providers
│ │ ├── page.tsx # Landing/home page
│ │ ├── globals.css # Global styles and Tailwind imports
│ │ ├── favicon.ico # Favicon
│ │ │
│ │ ├── sign-in/ # Authentication - Sign In
│ │ │ └── page.tsx # Sign in page
│ │ │
│ │ ├── sign-up/ # Authentication - Sign Up
│ │ │ └── page.tsx # Sign up page
│ │ │
│ │ ├── verify-otp/ # OTP Verification
│ │ │ └── page.tsx # OTP verification page
│ │ │
│ │ ├── sales/ # Sales pages (for cashier)
│ │ │ └── page.tsx # Sales/POS page
│ │ │
│ │ └── dashboard/ # Main dashboard (protected routes)
│ │ ├── page.tsx # Dashboard home page
│ │ │
│ │ ├── admin/ # Admin-specific pages
│ │ │ ├── page.tsx # Admin dashboard
│ │ │ └── categories/ # Category management
│ │ │ └── page.tsx # Categories page
│ │ │
│ │ ├── cashier/ # Cashier-specific pages
│ │ │ └── page.tsx # Cashier dashboard
│ │ │
│ │ ├── analytics/ # Analytics & reports
│ │ │ └── page.tsx # Analytics dashboard
│ │ │
│ │ ├── products/ # Product management
│ │ │ └── page.tsx # Products page
│ │ │
│ │ ├── suppliers/ # Supplier management
│ │ │ └── page.tsx # Suppliers page
│ │ │
│ │ ├── purchase-orders/ # Purchase order management
│ │ │ └── page.tsx # Purchase orders page
│ │ │
│ │ └── restock-recommendations/ # Restock alerts
│ │ └── page.tsx # Restock recommendations page
│ │
│ ├── components/ # React components
│ │ ├── AdminSidebar.tsx # Admin navigation sidebar
│ │ ├── Sidebar.tsx # General sidebar component
│ │ ├── Navbar.tsx # Navigation bar
│ │ ├── ProtectedRoute.tsx # Route protection HOC
│ │ ├── ErrorBoundary.tsx # Error boundary component
│ │ ├── Toast.tsx # Toast notification component
│ │ ├── DataTable.tsx # Reusable data table
│ │ ├── ProductForm.tsx # Product form component
│ │ ├── ProductModal.tsx # Product modal dialog
│ │ ├── ProductFilters.tsx # Product filtering component
│ │ ├── SearchAndFilter.tsx # Search and filter component
│ │ ├── EnhancedForm.tsx # Enhanced form component
│ │ ├── ProcurementOverview.tsx # Procurement overview
│ │ │
│ │ └── ui/ # Shadcn/Radix UI components
│ │ ├── badge.tsx # Badge component
│ │ ├── button.tsx # Button component
│ │ ├── card.tsx # Card component
│ │ ├── checkbox.tsx # Checkbox component
│ │ ├── dialog.tsx # Dialog/Modal component
│ │ ├── dropdown-menu.tsx # Dropdown menu component
│ │ ├── form.tsx # Form component wrapper
│ │ ├── input.tsx # Input component
│ │ ├── label.tsx # Label component
│ │ ├── select.tsx # Select dropdown component
│ │ ├── skeleton.tsx # Loading skeleton component
│ │ ├── sonner.tsx # Sonner toast wrapper
│ │ ├── table.tsx # Table component
│ │ ├── textarea.tsx # Textarea component
│ │ └── responsive-table.tsx # Responsive table wrapper
│ │
│ └── lib/ # Utility libraries
│ ├── utils.ts # Utility functions (cn, etc.)
│ │
│ ├── api/ # API client layer
│ │ ├── client.ts # Axios client configuration
│ │ ├── auth.ts # Authentication API calls
│ │ ├── products.ts # Products API calls
│ │ ├── categories.ts # Categories API calls
│ │ ├── sales.ts # Sales API calls
│ │ ├── inventory.ts # Inventory API calls
│ │ ├── suppliers.ts # Suppliers API calls
│ │ ├── purchase-orders.ts # Purchase orders API calls
│ │ ├── payments.ts # Payments API calls (Stripe)
│ │ ├── analytics.ts # Analytics API calls
│ │ └── stock.ts # Stock management API calls
│ │
│ ├── store/ # Redux store configuration
│ │ ├── index.ts # Store configuration & exports
│ │ ├── hooks.ts # Typed Redux hooks (useAppDispatch, useAppSelector)
│ │ ├── ReduxProvider.tsx # Redux Provider wrapper component
│ │ │
│ │ └── slices/ # Redux slices
│ │ ├── productsSlice.ts # Products state management
│ │ ├── salesSlice.ts # Sales state management
│ │ ├── suppliersSlice.ts # Suppliers state management
│ │ ├── purchasesSlice.ts # Purchase orders state
│ │ └── analyticsSlice.ts # Analytics state
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── index.ts # Hook exports
│ │ ├── useDebounce.ts # Debounce hook
│ │ ├── useDebouncedCallback.ts # Debounced callback hook
│ │ └── useThrottle.ts # Throttle hook
│ │
│ └── validations/ # Zod validation schemas
│ ├── signInSchema.ts # Sign in form validation
│ └── signUpSchema.ts # Sign up form validation
│
├── public/ # Static assets
│ └── manifest.json # PWA manifest
│
├── Configuration Files
│ ├── package.json # Dependencies and scripts
│ ├── tsconfig.json # TypeScript configuration
│ ├── next.config.ts # Next.js configuration
│ ├── next-env.d.ts # Next.js TypeScript declarations
│ ├── tailwind.config.js # Tailwind CSS configuration (implied)
│ ├── postcss.config.mjs # PostCSS configuration
│ ├── components.json # Shadcn UI configuration
│ ├── eslint.config.mjs # ESLint configuration
│ ├── FRONTEND_UX_ENHANCEMENTS.md # UX enhancement documentation
│ └── README.md # This file
- Supports light and dark themes via
next-themes - CSS variables for consistent theming
- Tailwind CSS utility classes
- Built on Radix UI primitives for accessibility
- Customized with Tailwind CSS
- Consistent design patterns across all pages
- Responsive design for mobile, tablet, and desktop
- System font stack for optimal performance
- Consistent heading hierarchy
- Readable body text with proper line height
- User registration with email verification
- OTP-based email verification
- JWT-based authentication
- Role-based access control (RBAC)
- Protected routes with redirect
- Persistent authentication state
- Role-specific dashboards (Admin, Cashier, Manager, Procurement)
- Real-time statistics and KPIs
- Quick actions and shortcuts
- Responsive sidebar navigation
- CRUD operations for products
- Product search and filtering
- Category-based organization
- Image upload support
- Stock level indicators
- Bulk operations
- Real-time stock tracking
- Stock adjustment interface
- Low stock alerts
- Restock recommendations
- Stock movement history
- Inventory valuation reports
- Fast and intuitive POS interface
- Product search and quick add
- Shopping cart management
- Multiple payment methods (Cash, Card, Stripe)
- Receipt generation
- Sales history
- Supplier CRUD operations
- Contact information management
- Supplier product catalog
- Performance tracking
- Purchase order creation and management
- Supplier selection
- Order status tracking
- Receiving interface
- Expected vs. actual delivery tracking
- Sales analytics with charts
- Revenue tracking
- Product performance metrics
- Inventory analytics
- Custom date range selection
- Export capabilities
- Stripe integration
- Secure payment handling
- Payment confirmation
- Transaction history
- Mobile-first approach
- Tablet optimization
- Desktop layouts
- Touch-friendly interfaces
- Responsive tables
- Node.js (v18 or higher)
- npm or yarn package manager
- Backend API running (see backend README)
-
Clone the repository
cd frontend -
Install dependencies
npm install
-
Set up environment variables
Create a
.env.localfile in the frontend directory:# API Configuration NEXT_PUBLIC_API_URL=http://localhost:3000 # Stripe Configuration NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_... # Application Configuration NEXT_PUBLIC_APP_NAME="Store Master" NEXT_PUBLIC_APP_URL=http://localhost:3001
-
Run the development server
npm run dev
-
Open the application
Navigate to http://localhost:3001
# Build the application
npm run build
# Start production server
npm run start| Script | Description |
|---|---|
npm run dev |
Start development server (hot reload) |
npm run build |
Build for production |
npm run start |
Start production server |
npm run lint |
Run ESLint |
/- Landing page/sign-in- User sign in/sign-up- User registration/verify-otp- OTP verification
/dashboard- Main dashboard (role-based)/dashboard/admin- Admin dashboard/dashboard/admin/categories- Category management/dashboard/cashier- Cashier dashboard/dashboard/analytics- Analytics and reports/dashboard/products- Product management/dashboard/suppliers- Supplier management/dashboard/purchase-orders- Purchase order management/dashboard/restock-recommendations- Restock alerts/sales- Point of Sale (POS) interface
- Full system access
- User management
- Category management
- Product management
- Sales management
- Procurement management
- Analytics access
- Product management
- Sales management
- Procurement management
- Analytics access
- Inventory adjustments
- POS access
- View products
- Create sales
- Limited dashboard access
- Supplier management
- Purchase order management
- Receive orders
- View inventory
The project uses Tailwind CSS 4 for styling:
- Utility-first approach
- Custom design tokens
- Responsive breakpoints
- Dark mode support
Theme variables are defined in globals.css:
--background,--foreground--primary,--secondary--accent,--muted--destructive,--success- Border radius, shadows, and more
The application uses Redux Toolkit for global state management:
- Product list
- Selected product
- Loading states
- Filters
- Cart items
- Active sale
- Sales history
- Supplier list
- Selected supplier
- Purchase orders
- PO status
- Dashboard metrics
- Chart data
import { useAppSelector, useAppDispatch } from '@/lib/store/hooks';
import { fetchProducts } from '@/lib/store/slices/productsSlice';
const products = useAppSelector(state => state.products.items);
const dispatch = useAppDispatch();
useEffect(() => {
dispatch(fetchProducts());
}, [dispatch]);All API calls are centralized in the src/lib/api/ directory:
// Example: Fetching products
import { getProducts } from '@/lib/api/products';
const products = await getProducts({ page: 1, limit: 10 });The Axios client is configured in client.ts:
- Base URL from environment variables
- JWT token interceptor
- Error handling
- Request/response interceptors
Debounce a value (useful for search inputs):
const debouncedSearch = useDebounce(searchTerm, 500);Debounce a callback function:
const debouncedFn = useDebouncedCallback(handleSearch, 500);Throttle a value:
const throttledValue = useThrottle(scrollY, 100);Forms use React Hook Form with Zod validation:
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { signInSchema } from '@/lib/validations/signInSchema';
const form = useForm({
resolver: zodResolver(signInSchema),
defaultValues: { email: '', password: '' }
});Required environment variables:
| Variable | Description | Example |
|---|---|---|
NEXT_PUBLIC_API_URL |
Backend API URL | http://localhost:3000 |
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY |
Stripe public key | pk_test_... |
NEXT_PUBLIC_APP_NAME |
Application name | Store Master |
NEXT_PUBLIC_APP_URL |
Frontend URL | http://localhost:3001 |
The application supports light and dark themes. Theme switching is handled by next-themes.
- Add CSS variable to globals.css
- Add Tailwind utility class
- Use in components:
className="bg-your-color"
sm: 640pxmd: 768pxlg: 1024pxxl: 1280px2xl: 1536px
All components are designed mobile-first and scale up:
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
{/* Content */}
</div>Toast notifications use Sonner:
import { toast } from 'sonner';
toast.success('Product created successfully');
toast.error('Failed to create product');
toast.info('Processing...');The project uses Shadcn UI components built on Radix UI:
- Fully accessible
- Customizable
- Type-safe
- Composable
npx shadcn-ui@latest add [component-name]- Code Splitting: Automatic with Next.js App Router
- Image Optimization: Next.js Image component
- Lazy Loading: Dynamic imports for heavy components
- Debouncing: Search and filter operations
- Memoization: React.memo and useMemo for expensive computations
- JWT tokens stored in httpOnly cookies (handled by backend)
- No sensitive data in localStorage
- Input validation on client and server
- XSS prevention with proper escaping
- CSRF protection
- Error boundaries for component errors
- Global error handling in API client
- User-friendly error messages
- Logging for debugging
- Follow the existing code structure
- Use TypeScript types properly
- Write meaningful component names
- Add comments for complex logic
- Test on multiple screen sizes
- Follow ESLint rules
UNLICENSED - Private project
For support or questions, refer to the documentation or contact the development team.
See FRONTEND_UX_ENHANCEMENTS.md for planned improvements.
Built with ❤️ using Next.js, React, TypeScript, and Tailwind CSS
This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.
To learn more about Next.js, take a look at the following resources:
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
You can check out the Next.js GitHub repository - your feedback and contributions are welcome!
The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.
Check out our Next.js deployment documentation for more details.