Frontend Complete doc Table of Contents Project Overview Technology Stack Getting Started Project Structure Features & Modules Authentication & Authorization API Integration Component Library State Management Routing & Navigation Development Guidelines Deployment Troubleshooting Project Overview OnMart POS Frontend is a modern Point of Sale (POS) system built for retail management. The application provides comprehensive functionality for managing sales, inventory, customers, and reporting across multiple outlets. Key Features Role-based Access Control : Master Admin, Super Admin, Admin, and Cashier roles POS Terminal : Fast checkout and transaction processing Inventory Management : Products, categories, brands, and stock control Customer Management : Customer database and transaction history Reporting & Analytics : Sales reports, dashboard analytics, and transaction tracking Multi-outlet Support : Manage multiple store locations Shift Management : Cashier shift tracking and reporting Technology Stack Core Framework Next.js 15.5.12 : React framework with App Router React 19 : Latest React version TypeScript 5 : Type-safe development Tailwind CSS 4 : Utility-first CSS framework UI Components & Libraries Radix UI : Accessible component primitives Dialog, Popover, Checkbox, Separator, Slot, Tooltip Headless UI : Unstyled, accessible UI components Lucide React : Icon library Heroicons : Additional icon set shadcn/ui : Component library (New York style) Data Fetching & State Management SWR 2.3.4 : React Hooks for data fetching Axios 1.10.0 : HTTP client React Hook Form 7.59.0 : Form management Data Visualization Recharts 2.15.3 : Charting library for dashboard analytics @tanstack/react-table 8.21.3 : Table management Additional Libraries date-fns 4.1.0 : Date manipulation SweetAlert2 11.22.0 : Beautiful alert dialogs React Hot Toast 2.5.2 : Toast notifications class-variance-authority : Dynamic class management clsx & tailwind-merge : Class utility functions Development Tools ESLint 9 : Code linting Turbopack : Fast bundler (Next.js dev mode) Getting Started Prerequisites Node.js 20+ installed npm, yarn, pnpm, or bun package manager Access to OnMart backend API Installation Clone the repository git clone cd onmart-pos-frontend Install dependencies npm install # or yarn install # or pnpm install Configure environment variables Create or update .env.local file: NEXT_PUBLIC_API_URL=http://localhost:3000/api ORIGIN_CORS=http://localhost:3711 Run development server npm run dev # or yarn dev The application will start on http://localhost:3711 Available Scripts # Start development server with Turbopack npm run dev # Build for production npm run build # Start production server npm run start # Run ESLint npm run lint Project Structure onmart-pos-frontend/ ├── src/ │ ├── app/ # Next.js App Router │ │ ├── (auth)/ # Authentication routes │ │ │ ├── login/ │ │ │ ├── logout/ │ │ │ └── redirect/ │ │ ├── (dashboard)/ # Protected dashboard routes │ │ │ ├── dashboard/ # Main dashboard │ │ │ ├── products/ # Product management │ │ │ ├── categories/ # Category management │ │ │ ├── brands/ # Brand management │ │ │ ├── promos/ # Promotions & discounts │ │ │ ├── outlets/ # Outlet management │ │ │ ├── customers/ # Customer management │ │ │ ├── invoices/ # Invoice history │ │ │ ├── transactions/ # Transaction reports │ │ │ ├── posterminal/ # POS Terminal │ │ │ ├── myshift/ # Cashier shift management │ │ │ ├── usermanagement/# User management │ │ │ └── accountsettings/# Account settings │ │ ├── api/ # API routes │ │ ├── layout.tsx # Root layout │ │ ├── page.tsx # Home page │ │ └── globals.css # Global styles │ ├── components/ # React components │ │ ├── ui/ # UI primitives │ │ ├── icons/ # Custom icons │ │ ├── layouts/ # Layout components │ │ └── page.tsx # Page component │ ├── features/ # Feature modules │ │ ├── auth/ # Authentication │ │ ├── products/ # Product features │ │ ├── categories/ # Category features │ │ ├── brands/ # Brand features │ │ ├── promos/ # Promo features │ │ ├── outlets/ # Outlet features │ │ ├── customers/ # Customer features │ │ ├── invoices/ # Invoice features │ │ ├── transactions/ # Transaction features │ │ ├── posTerminal/ # POS Terminal features │ │ ├── myshift/ # Shift management │ │ ├── userManagement/ # User management │ │ └── accountSettings/ # Account settings │ ├── hooks/ # Custom React hooks │ │ └── use-mobile.ts # Mobile detection hook │ ├── lib/ # Utility libraries │ │ ├── api/ # API configuration │ │ │ └── endpoints.ts # API endpoints │ │ ├── fetchWithAuth.ts # Server-side fetch │ │ ├── fetchWithAuthClient.ts# Client-side fetch │ │ ├── utils.ts # Utility functions │ │ └── alert.ts # Alert utilities │ ├── types/ # TypeScript types │ │ ├── product.ts # Product types │ │ └── profile.ts # Profile types │ └── middleware.ts # Next.js middleware ├── public/ # Static assets ├── .env.local # Environment variables ├── next.config.ts # Next.js configuration ├── tailwind.config.ts # Tailwind configuration ├── tsconfig.json # TypeScript configuration ├── components.json # shadcn/ui configuration └── package.json # Dependencies Directory Explanation /src/app Contains Next.js App Router pages and layouts. Organized with route groups: (auth) : Public authentication pages (dashboard) : Protected dashboard pages /src/components Reusable React components: ui/ : Base UI components (buttons, inputs, tables, etc.) icons/ : Custom SVG icons for navigation layouts/ : Layout components like dashboardLayout.tsx /src/features Feature-specific components organized by domain: Each feature contains: actions.tsx , columns.tsx , formX.tsx , listX.tsx Follows a consistent pattern for CRUD operations /src/lib Utility functions and configurations: API endpoint definitions Authentication helpers Shared utilities Features & Modules 1. Dashboard Path : /dashboard Roles : Master Admin, Super Admin, Admin, Cashier Features : Sales summary with key metrics (Gross Sales, Net Sales, Gross Profit) Transaction count and average sale tracking Day of week sales analysis (Bar chart) Hourly sales trends (Area chart) Top-selling items table Category analysis by volume and sales (Pie charts) Date range filtering Multi-outlet filtering Components : src/app/(dashboard)/dashboard/page.tsx Uses Recharts for data visualization 2. POS Terminal Path : /posterminal Roles : Cashier Features : Product search and barcode scanning Shopping cart management Customer selection Payment processing Multiple payment methods Receipt generation Shift management integration Components : src/features/posTerminal/productSearch.tsx src/features/posTerminal/cartItemList.tsx src/features/posTerminal/customerModal.tsx src/features/posTerminal/formPosTerminal.tsx src/features/posTerminal/openShiftModal.tsx 3. Product Management Path : /products Roles : Master Admin, Super Admin, Admin Features : Product CRUD operations Product listing with search and filters Stock management Category and brand assignment Barcode management Bulk import (CSV/Excel) Export functionality Components : src/features/products/listProducts.tsx src/features/products/formProduct.tsx src/features/products/columns.tsx src/features/products/actions.tsx API Endpoints : GET /api/products - List products POST /api/products - Create product PUT /api/products/:id - Update product DELETE /api/products/:id - Delete product POST /api/products/import-csv - Import CSV POST /api/products/import-excel - Import Excel GET /api/products/export-csv - Export CSV 4. Category Management Path : /categories Roles : Master Admin, Super Admin, Admin Features : Category CRUD operations Category listing Product count per category Components : src/features/categories/listCategory.tsx src/features/categories/formCategory.tsx src/features/categories/columns.tsx 5. Brand Management Path : /brands Roles : Master Admin, Super Admin, Admin Features : Brand CRUD operations Brand listing Product count per brand Components : src/features/brands/formBrand.tsx src/features/brands/columns.tsx 6. Promotions & Discounts Path : /promos Roles : Master Admin, Super Admin, Admin Features : Promo/discount creation and management Discount rules configuration Active/inactive status management 7. Outlet Management Path : /outlets Roles : Master Admin, Super Admin Features : Multiple store location management Outlet-specific inventory Per-outlet reporting 8. Customer Management Path : /customers Roles : All roles Features : Customer database Customer information management Purchase history Customer search Components : src/features/customers/ (contains customer CRUD components) 9. Invoice Management Path : /invoices Roles : All roles Features : Invoice history Invoice details view Invoice search and filtering Invoice printing Components : src/features/invoices/ (contains invoice list and detail views) 10. Transaction Reports Path : /transactions Roles : Master Admin, Super Admin, Admin Features : Transaction history Advanced filtering (date, outlet, status) Transaction void functionality Transaction refund functionality Export capabilities Components : src/features/transactions/ (contains transaction reports) API Endpoints : GET /api/transactions - List transactions GET /api/transactions/:id/invoice - Get invoice details PATCH /api/transactions/:id/void - Void transaction PATCH /api/transactions/:id/refund - Refund transaction 11. My Shift Path : /myshift Roles : Cashier Features : Shift start/end tracking Shift summary Cash reconciliation Shift history Components : src/features/myshift/listMyshift.tsx src/features/myshift/formMyShift.tsx src/features/myshift/columns.tsx 12. User Management Path : /usermanagement Roles : Master Admin, Super Admin, Admin Features : User CRUD operations Role assignment User status management Password management Components : src/features/userManagement/listUser.tsx src/features/userManagement/formUser.tsx src/features/userManagement/columns.tsx 13. Account Settings Path : /accountsettings Roles : All roles Features : Profile information Password change User preferences Components : src/features/auth/accountPage.tsx Authentication & Authorization Authentication Flow Login Process User enters credentials on /login loginAction validates credentials with backend On success, JWT token is stored in cookies User profile is stored in cookies Redirect to /redirect then to appropriate dashboard Token Management Access token stored in access_token cookie Profile data stored in profile cookie "Remember Me" extends cookie lifetime to 7 days Token is automatically included in API requests Logout Process /logout page calls logout API Clears cookies Redirects to /login Middleware Protection File : src/middleware.ts // Public routes accessible without authentication const publicRoutes = ["/login", "/auth/redirect"]; // Logic: // - If logged in + accessing public route → redirect to /dashboard // - If not logged in + accessing private route → redirect to /login Protected Routes : All routes except /login and /auth/redirect require authentication Static files ( /_next/static , images, etc.) are excluded from middleware Role-Based Navigation File : src/components/layouts/dashboardLayout.tsx Navigation items are filtered based on user role: Master Admin Dashboard Reports (Transactions) Library (Products, Categories, Brands, Promos) Outlets Customers Invoices User Management Account Settings Super Admin / Admin Dashboard Reports (Transactions) Library (Products, Categories, Brands, Promos) Customers Invoices User Management Account Settings Cashier Customers My Shift POS Terminal Invoices Account Settings Authentication Helpers Client-Side Fetch File : src/lib/fetchWithAuthClient.ts // Automatically adds Authorization header from localStorage const fetchWithAuthClient = async (input, init) => { const token = localStorage.getItem("access_token"); headers.set("Authorization", `Bearer ${token}`); return fetch(input, { ...init, headers }); }; Server-Side Fetch File : src/lib/fetchWithAuth.ts For server components and API routes with cookie-based authentication. API Integration Base URL Configuration File : src/lib/api/endpoints.ts // Production API const baseUrl = "https://posapi.onemart.id/api"; // For local development, uncomment: // const baseUrl = "http://localhost:3710/api"; API Endpoints All endpoints are defined in src/lib/api/endpoints.ts : Authentication POST /api/auth/login - User login POST /api/auth/logout - User logout GET /api/auth/me - Get current user PUT /api/auth/me/password - Change password Products GET /api/products - List products POST /api/products - Create product PUT /api/products/:id - Update product DELETE /api/products/:id - Delete product POST /api/products/import-csv - Import CSV POST /api/products/import-excel - Import Excel GET /api/products/export-csv - Export CSV Categories GET /api/categories - List categories POST /api/categories - Create category PUT /api/categories/:id - Update category DELETE /api/categories/:id - Delete category Brands GET /api/brands - List brands POST /api/brands - Create brand PUT /api/brands/:id - Update brand DELETE /api/brands/:id - Delete brand Promotions GET /api/promos - List promotions POST /api/promos - Create promotion PUT /api/promos/:id - Update promotion DELETE /api/promos/:id - Delete promotion Outlets GET /api/outlets - List outlets POST /api/outlets - Create outlet PUT /api/outlets/:id - Update outlet DELETE /api/outlets/:id - Delete outlet Customers GET /api/customers - List customers POST /api/customers - Create customer PUT /api/customers/:id - Update customer DELETE /api/customers/:id - Delete customer Payment Methods GET /api/payment-methods - List payment methods Shifts GET /api/cashier/shifts - List shifts POST /api/cashier/shifts - Start shift PUT /api/cashier/shifts/:id - End shift Transactions GET /api/transactions - List transactions GET /api/transactions/:id/invoice - Get invoice details PATCH /api/transactions/:id/void - Void transaction PATCH /api/transactions/:id/refund - Refund transaction Dashboard GET /api/dashboard/summary - Dashboard summary Query params: dateStart , dateEnd , outletId Users GET /api/users - List users POST /api/users - Create user PUT /api/users/:id - Update user DELETE /api/users/:id - Delete user Roles GET /api/roles - List roles Making API Calls Using SWR (Recommended for GET requests) import useSWR from 'swr'; import { fetchWithAuthClient } from '@/lib/fetchWithAuthClient'; import endpoints from '@/lib/api/endpoints'; const { data, error, isLoading, mutate } = useSWR( endpoints.product.url, fetchWithAuthClient ); Using Axios import axios from 'axios'; import endpoints from '@/lib/api/endpoints'; const response = await axios({ url: endpoints.product.url, method: endpoints.product.method, headers: { Authorization: `Bearer ${token}`, }, data: productData, }); Using fetch directly import { fetchWithAuthClient } from '@/lib/fetchWithAuthClient'; import endpoints from '@/lib/api/endpoints'; const response = await fetchWithAuthClient( endpoints.product.url, { method: 'POST', body: JSON.stringify(productData), headers: { 'Content-Type': 'application/json', }, } ); Component Library UI Components The application uses shadcn/ui components with Radix UI primitives. Location : src/components/ui/ Available Components Button ( button.tsx ) Variants: default, destructive, outline, secondary, ghost, link Sizes: default, sm, lg, icon Input ( input.tsx ) Standard text input Checkbox ( checkbox.tsx ) Accessible checkbox component Select ( select.tsx ) Dropdown select component Textarea ( textarea.tsx ) Multi-line text input