{"schemaVersion":"1.0","lastUpdated":"2026-09-02","project":{"name":"AP Malls","category":"Full-stack retail commerce and point-of-sale platform","status":"Active development","summary":"AP Malls connects a customer storefront, role-aware back office, inventory ledger, delivery operations, barcode printing, and cashier POS in one retail system.","elevatorPitch":"AP Malls is a full-stack retail platform designed for both online ordering and physical counter sales. Customers browse a hierarchical catalog, manage carts and addresses, place orders, and confirm delivery. Staff use permission-scoped workspaces for catalog, inventory, fulfillment, delivery, access control, and POS billing. A Next.js application provides the user experiences and secure backend-for-frontend routes, while a Laravel API owns business rules, transactional stock, payments, and PostgreSQL persistence.","problem":"A retail business often manages its website, counter billing, stock, labels, delivery staff, and permissions in disconnected tools. That produces duplicate catalog work, inconsistent inventory, unclear ownership, and unreliable handoffs between roles.","solution":"The project uses one shared catalog and transactional backend so the storefront, admin operations, delivery workflow, and POS all work from the same products, prices, stock balances, orders, payments, and role rules.","architectureStyle":"A Next.js App Router frontend and backend-for-frontend layer consuming a versioned Laravel REST API backed by Eloquent and PostgreSQL/Supabase."},"developers":[{"name":"Abhishek Kumar Chaudhary","role":"Full-stack Developer","location":"Budhanagar Colony, Madhubani, Bihar, India","image":"https://avatars.githubusercontent.com/u/93211705?v=4","summary":"Builds the connected customer, administration, and operational experience across Next.js and Laravel, with a focus on maintainable data flow, role-aware interfaces, transactional commerce behavior, and practical debugging.","highlights":["Builds responsive and performant web applications with a strong eye for UI and UX.","Develops responsive Next.js and React interfaces with TypeScript, Tailwind CSS, reusable components, and API-backed state.","Integrates Laravel services, validation, resources, authentication, permissions, and PostgreSQL-backed workflows across the application.","Works across catalog, cart, checkout, inventory, POS, barcode, delivery, printing, and access-control features.","Broader experience includes JavaScript, Node.js, .NET, Express, MongoDB, and SQL.","Professional experience includes Software Developer at IISERVZ and an MCA from AKTU."],"links":[{"label":"Website","href":"https://www.abhishek-chaudhary.com/"},{"label":"GitHub","href":"https://github.com/abhishekkumarchaudhary1"}]},{"name":"Md. Faiyyaj Alam","role":"Website designer, full-stack developer, PHP and Laravel developer","location":"Purnea, Bihar, India","image":"https://avatars.githubusercontent.com/u/74866346?v=4","summary":"Contributes full-stack implementation experience with a practical focus on PHP, Laravel, interface delivery, and the operational needs of a retail application.","highlights":["Full-stack web development profile focused on PHP, Laravel, Python, and software delivery.","Public GitHub profile with 62 repositories as of the latest sourced profile read.","Contributes practical UI, admin, and backend implementation experience to the project."],"links":[{"label":"GitHub","href":"https://github.com/MdFaiyyajAlam"}]}],"stats":[{"value":"3","label":"Experiences","text":"Storefront, admin panel, and POS dashboard"},{"value":"1","label":"Shared catalog","text":"Products power online shopping and counter sales"},{"value":"80mm","label":"Receipt style","text":"Simple supermarket-style thermal bill output"}],"modules":[{"icon":"storefront","title":"Customer Storefront","text":"Public shopping pages for home, products, categories, product details, cart, wishlist, checkout, account access, support, and policies."},{"icon":"commerce","title":"Admin Operations","text":"Role-aware admin pages for dashboard insights, categories, brands, units, products, banners, orders, cash registers, barcode templates, and security."},{"icon":"pos","title":"POS Billing","text":"Dedicated cashier workspace with register sessions, product search, barcode scan flow, held bills, checkout, printable receipts, reports, and order edits."},{"icon":"barcode","title":"Barcode System","text":"Admin product barcode generation, template management, printable labels, QR-capable layouts, and scan-friendly product lookup for store counters."},{"icon":"inventory","title":"Inventory Ledger","text":"Authoritative stock balances, immutable movements, reconciliation indicators, low-stock visibility, and reason-based physical adjustments."},{"icon":"delivery","title":"Delivery Operations","text":"Assignment lifecycle, courier handover reporting, customer confirmation, OTP verification, COD settlement, disputes, and manager resolution."},{"icon":"access","title":"Access Control","text":"User administration, protected system roles, grouped permission assignment, role-specific dashboards, and backend-enforced capability checks."}],"technologyLayers":[{"icon":"frontend","title":"Frontend","text":"Next.js renders public, customer, staff, and POS experiences from shared typed contracts.","points":["Next.js App Router","Role-aware screens","Customer, admin, and POS surfaces"],"details":["Server Components load public catalog content close to the API, while focused Client Components handle cart updates, forms, dialogs, delivery actions, and POS interactions.","URL-backed search, category, sorting, filters, tabs, and pagination keep important views shareable and browser-navigation friendly.","Next Route Handlers act as a backend-for-frontend layer, forwarding authenticated requests without exposing the Laravel bearer token to browser JavaScript.","Reusable providers coordinate authentication, cart, and wishlist state; optimistic cart updates are reconciled against authoritative backend totals."],"packages":["Next.js 16.2.10","React 19.2.4","TypeScript 5","Tailwind CSS 4","Lucide React","Sonner"]},{"icon":"backend","title":"Backend","text":"Laravel owns validation, business rules, authorization, transactions, resources, and persistence.","points":["Laravel REST API","Service and resource layers","PostgreSQL-backed commerce data"],"details":["Versioned `/api/v1` controllers keep transport concerns separate from services that implement catalog, checkout, stock, POS, payment, delivery, and access-control behavior.","Service contracts and dependency injection keep domain operations replaceable and testable, while API Resources normalize response shapes for frontend consumers.","Eloquent models, migrations, factories, and seeders define the database lifecycle and provide repeatable local or disposable environments.","Critical writes use database transactions, row locking, status guards, and idempotency keys to avoid duplicated stock or payment effects."],"packages":["PHP 8.3","Laravel 13.8","Eloquent ORM","PostgreSQL","Laravel Sanctum"]},{"icon":"security","title":"Security and Access","text":"Authentication and authorization are enforced at both presentation and API boundaries.","points":["Sanctum token flow","Roles and permissions","Protected role-specific workspaces"],"details":["Laravel Sanctum issues API tokens that the Next.js layer stores in an httpOnly, same-site cookie and forwards only from server-side route handlers.","Spatie Permission models capabilities with `module.action` names; Laravel middleware remains authoritative even when the frontend hides an action.","Super Admin and self-protection rules prevent accidental demotion, deletion, deactivation, or destructive edits to access-critical records.","Customer shopping actions, staff workspaces, Cashier POS isolation, and Delivery Boy ownership checks are all role-aware."],"packages":["Laravel Sanctum","Spatie Laravel Permission","Spatie Activity Log","Laravel Socialite"]},{"icon":"inventory","title":"Catalog and Inventory","text":"A structured catalog feeds every channel while one ledger remains the source of stock truth.","points":["Two-level categories","Backend filtering and pagination","Auditable stock movements"],"details":["Categories are limited to parent and subcategory levels. Products belong to an active leaf category, while selecting a parent returns products from all active descendants.","Search, category, pricing, brand, feature flags, sorting, and pagination are composed by the backend so totals stay accurate.","The stocks table is authoritative; product quantity is maintained only as a compatibility mirror.","Product creation, checkout, POS sales, cancellations, received purchases, returns, and manual adjustments all pass through transactional stock services."],"packages":["Eloquent ORM","PostgreSQL row locks","Laravel migrations","Laravel seeders"]},{"icon":"pos","title":"Commerce and POS","text":"Online orders and counter billing share catalog, pricing, stock, order, and payment rules.","points":["Orders and payments","Cash register sessions","Receipts and balance tracking"],"details":["Customers maintain server-backed carts and wishlists, save addresses, place orders, and track fulfillment from their account.","Cashiers work only inside POS, open their assigned register session, search or scan products, hold and recall bills, collect payment, and print receipts.","Prices, product discounts, taxes, and totals are derived by backend services rather than trusted from browser payloads.","Completed POS orders can be adjusted through controlled order-edit flows that preserve prior payments and collect only any additional balance."],"packages":["React state providers","Laravel service transactions","80mm print CSS","Intl.NumberFormat"]},{"icon":"delivery","title":"Delivery and Confirmation","text":"Delivery completion requires an auditable handoff instead of a one-sided courier action.","points":["Assignment state machine","Customer consent","Idempotent COD settlement"],"details":["Delivery Boys accept, reject, pick up, and move assignments out for delivery through ordered state transitions and ownership checks.","Reporting a handover does not complete the order. The Customer confirms receipt in My Orders or provides a five-minute, hashed one-time code to the courier.","Customer disputes lock reassignment until an authorized manager either confirms the handoff with remarks or reopens the order for delivery.","Finalization is row-locked and idempotent so a COD confirmation creates exactly one completed Cash payment."],"packages":["Laravel hashing","Database transactions","Spatie permissions","Time-bound OTP records"]},{"icon":"printing","title":"Media and Printing","text":"Product labels, counter receipts, and staff invoices use purpose-built output formats.","points":["Barcode and QR labels","80mm receipts","A4 sales invoices"],"details":["Products can receive settings-backed generated barcodes or manually entered values, with the generation source and barcode type preserved.","Active label templates control dimensions and content for bulk printable barcode pages, including QR-capable layouts.","POS receipts use a compact 80mm print layout; staff order details render a separate A4 invoice instead of printing the responsive management screen.","Image processing, PDF tooling, and spreadsheet export packages are available for media normalization and operational outputs."],"packages":["Picqer Barcode Generator","Milon Barcode","Simple QR Code","Dompdf","Intervention Image","Laravel Excel"]}],"roleExperiences":[{"role":"Customer","purpose":"Discover products, place orders, and control personal delivery confirmation.","capabilities":["Catalog and category browsing","Cart, wishlist, addresses, and checkout","Order tracking, OTP generation, confirmation, and disputes"]},{"role":"Super Admin","purpose":"Control the complete platform and its access model.","capabilities":["Store-wide metrics and operations","Catalog, barcode, delivery, banners, and registers","Users, roles, and grouped permissions"]},{"role":"Admin","purpose":"Run delegated administration without bypassing protected system records.","capabilities":["Permission-scoped catalog and order management","Delivery oversight and dispute resolution","Assigned access-control operations"]},{"role":"Store Manager","purpose":"Manage day-to-day inventory, fulfillment, delivery, and store performance.","capabilities":["Stock balances, movements, and adjustments","Order fulfillment and delivery assignment","Revenue, cost, margin, and exception visibility"]},{"role":"Cashier","purpose":"Complete fast, session-bound counter billing.","capabilities":["Assigned cash register sessions","Product scan, search, hold, recall, and payment","Thermal receipt printing and current-session sales"]},{"role":"Delivery Boy","purpose":"Manage only personally assigned deliveries and customer handoffs.","capabilities":["Availability and owned assignments","Ordered delivery status transitions","Handover reporting and customer-provided OTP confirmation"]}],"workflows":[{"label":"Shopping","text":"Customer browses products, adds items to cart or wishlist, accepts terms on signup, checks out, and tracks orders."},{"label":"Catalog","text":"Admin maintains product details, pricing, tax, stock, media, barcode data, categories, brands, units, and product visibility."},{"label":"Promotion","text":"Admin creates website banners for homepage sliders and offer sections, with image or video support and scheduled visibility."},{"label":"Counter Sale","text":"Cashier opens the assigned register, scans or searches products, holds bills when needed, recalls them, accepts payment, and prints receipts."},{"label":"Inventory","text":"Every stock-changing event records a transactional movement; managers investigate exceptions and use reason-required adjustments for physical corrections."},{"label":"Delivery","text":"A confirmed order is assigned, progressed by the courier, reported as handed over, and completed only after customer or manager confirmation."}],"architecture":{"summary":"The frontend is not trusted with business totals or authorization. It gathers user intent, presents optimistic feedback where appropriate, and sends minimal payloads through server-side proxies. Laravel validates the request, checks permissions, executes domain services, persists a transaction, and returns normalized resources.","requestFlow":["Browser interaction in a Server or Client Component","Next.js page data helper or same-origin Route Handler","Sanctum bearer token attached only on the server","Versioned Laravel controller and Form Request validation","Permission middleware and domain service contract","Eloquent transaction against PostgreSQL/Supabase","API Resource response normalized into shared TypeScript models","Role-aware UI refresh or optimistic-state reconciliation"],"dataPrinciples":["The Laravel API is authoritative for permissions, prices, totals, stock, order state, and payment state.","Stock movements are immutable audit events; product stock is only a synchronized compatibility field.","URL parameters represent catalog filters and pagination so browsing state is reproducible.","Critical completion flows are row-locked and idempotent to make retries safe.","Public project-profile data is static and contains no credentials or private operational records."]},"engineeringHighlights":[{"icon":"catalog","title":"Accurate hierarchical browsing","challenge":"Frontend-only category filtering operated on one page of products and returned incorrect parent totals.","solution":"A public category-tree API and descendant-aware backend product query now combine category, search, sort, filters, and pagination.","outcome":"Parent and child browsing, counts, and pagination now agree across homepage, category pages, and product listings."},{"icon":"inventory","title":"One source of inventory truth","challenge":"Independent product quantities and stock rows could diverge after purchases, sales, cancellations, or adjustments.","solution":"Stock services, row locking, movement keys, and immutable adjustments route every inventory event through the ledger.","outcome":"Store Managers can audit how a balance changed and reconcile legacy discrepancies without silent overwrites."},{"icon":"performance","title":"Stable rapid cart updates","challenge":"Fast quantity clicks allowed older server responses to overwrite newer customer intent, causing visible bouncing.","solution":"The cart provider retains the latest desired quantity, applies optimistic totals, and reconciles responses against pending mutations.","outcome":"The interface stays responsive while final prices and totals still come from the backend."},{"icon":"delivery","title":"Consent-based delivery completion","challenge":"A courier could previously complete delivery and COD settlement without customer acknowledgement.","solution":"A two-party handoff records courier reporting, customer confirmation or OTP, disputes, timestamps, and manager resolution.","outcome":"Delivered metrics and COD payments reflect an auditable confirmation instead of a one-sided status update."},{"icon":"security","title":"Permission-driven experiences","challenge":"A shared interface exposed irrelevant navigation and actions even when APIs correctly rejected them.","solution":"Central role helpers now shape sidebars, headers, dashboards, product actions, and POS isolation while middleware enforces every operation.","outcome":"Each role sees a focused workspace, and hidden controls never replace backend authorization."},{"icon":"printing","title":"Output designed for its paper","challenge":"Printing responsive screens clipped tables, while barcode labels lacked reliable quiet zones and scaling.","solution":"Dedicated templates now target small barcode labels, 80mm thermal receipts, and A4 staff invoices independently.","outcome":"Each output is readable, scannable, and sized for its real operational use."}],"operatingPrinciples":[{"icon":"catalog","title":"Catalog first","text":"Product data feeds browsing, billing, labels, and admin details."},{"icon":"barcode","title":"Counter ready","text":"Cashiers can scan, hold, recall, edit, pay, and print."},{"icon":"access","title":"Role separated","text":"Admins, customers, managers, delivery staff, and cashiers each get purpose-built screens."},{"icon":"commerce","title":"Promotion aware","text":"Sliders and offer banners are controlled from the backend."}],"packages":[{"group":"Frontend application","description":"Rendering, interaction, styling, icons, feedback, and static analysis.","items":[{"name":"Next.js 16.2.10","purpose":"App Router pages, layouts, Server Components, Route Handlers, caching, and metadata"},{"name":"React 19.2.4","purpose":"Interactive forms, providers, dialogs, optimistic workflows, and role-aware components"},{"name":"TypeScript 5","purpose":"Shared API contracts and compile-time checking across components and routes"},{"name":"Tailwind CSS 4","purpose":"Responsive implementation of the AP Malls design system and print layouts"},{"name":"Lucide React","purpose":"Consistent semantic icons across storefront, admin, delivery, and POS"},{"name":"Sonner","purpose":"Accessible success, validation, permission, and network feedback"}]},{"group":"Backend and data","description":"Versioned APIs, persistence, authentication, permissions, media, and operational documents.","items":[{"name":"PHP 8.3 and Laravel 13.8","purpose":"REST controllers, validation, services, dependency injection, jobs, migrations, and API resources"},{"name":"Laravel Sanctum","purpose":"Token authentication between Next.js server routes and protected Laravel endpoints"},{"name":"PostgreSQL / Supabase","purpose":"Relational commerce data, constraints, transactional locking, and hosted persistence"},{"name":"Spatie Permission","purpose":"Roles, capabilities, permission middleware, and protected administrative actions"},{"name":"Spatie Activity Log","purpose":"Auditable model and operational changes"},{"name":"Socialite","purpose":"Google authentication integration capability"},{"name":"Intervention Image","purpose":"Server-side product and content image processing"},{"name":"Laravel Excel","purpose":"Spreadsheet import and export capability for operational data"}]},{"group":"Barcode and document output","description":"Machine-readable product labels and purpose-sized print documents.","items":[{"name":"Picqer Barcode Generator","purpose":"Barcode generation for product labels and scanning workflows"},{"name":"Milon Barcode","purpose":"Laravel barcode rendering used by printable label templates"},{"name":"Simple QR Code","purpose":"QR-capable barcode template output"},{"name":"Dompdf","purpose":"Backend PDF document generation capability"},{"name":"Browser print CSS","purpose":"Dedicated 80mm receipts, A4 sales invoices, and label-sheet previews"}]},{"group":"Quality and developer tooling","description":"Repeatable verification of backend behavior, frontend contracts, and API documentation.","items":[{"name":"PHPUnit 12","purpose":"Feature coverage for authorization, stock, POS, delivery, and lifecycle rules"},{"name":"ESLint 9","purpose":"Next.js and React code-quality checks"},{"name":"TypeScript compiler","purpose":"No-emit application-wide contract verification"},{"name":"Laravel Postman generator","purpose":"Regenerated API collection from the implemented Laravel routes"},{"name":"Laravel Pint","purpose":"Consistent backend PHP formatting"}]}],"links":[{"label":"Browse Products","href":"/products"},{"label":"Contact","href":"/contact"},{"label":"Project Profile API","href":"/about-project/api"}]}