GBGX-ERP
FRONTEND

• The root layout establishes the HTML structure and loads optimized typography using Next.js font handling.
• Inter is used for body text and Montserrat for headings.
• The provider layer wraps the application with AuthProvider for user/session state, QueryProvider for TanStack Query, and Sonner's Toaster for global notifications.

• Tailwind CSS v4 with a custom @theme configuration.
• Brutalist visual language with sharp edges and zero-radius surfaces.
• Monochromatic surface palette.
• Electric Lime accent for call-to-action elements.
• Reusable .btn-primary and .card-brutalist component classes.

The design system is intentionally consistent across the ERP, while module-specific pages compose the shared primitives rather than creating independent visual systems.

• Base URL: /api/v1 — requests are routed to the Next.js BFF.
• X-Requested-With: XMLHttpRequest is added to requests for CSRF protection.
• Axios errors are translated into user-facing Sonner notifications.
• 422 responses are parsed to expose field-specific validation messages.
• 401 responses trigger a user notification and redirect toward login.

• API hooks under lib/api wrap backend interactions in reusable query and mutation abstractions.
• useQuery handles standard server-state retrieval.
• useInfiniteQuery supports paginated/infinite data sets such as inventory and sales tables.
• useMutation handles state-changing operations.
• Successful mutations invalidate related query keys so the UI rehydrates from current backend state.

The frontend exposes TypeScript interfaces for important domain objects such as ProductCatalog, StockMove, and SalesOrder. These types create a shared contract for components and API hooks.

The BFF is the security and routing boundary between browser code and backend services.

POST /auth/login is handled specially. On successful authentication, the BFF extracts access_token from the backend response, stores it in the HttpOnly cookie, and returns a sanitized response to the browser without exposing the token.

The architecture separates browser identity from backend service authentication. The browser proves its session through the cookie; the BFF converts that session into the backend authentication context and adds the server-to-server trust signal.

The main dashboard uses /analytics/dashboard-summary to retrieve dashboard data through a consolidated endpoint rather than issuing many independent KPI calls.

• The seven-day earnings visualization uses a dependency-free CSS calculation based on square-root normalization of revenue to produce more readable bar heights.

• Customers and Employees support strict frontend input patterns, including 10-digit phone validation.
• Successful provisioning can expose an auto-generated portal password in a persistent toast so the administrator can securely transfer it to the user.
• Entities use a multi-step drawer and derive roles from Entity Type.
• The Central Warehouse option is disabled when a Central Warehouse already exists.

• System Logs exposes stock_moves and event_outbox status for operational diagnostics.
• Finance supports invoice listing, invoice-number override, and Credit Note issuance.
• Admin tools support generation of time-limited password reset links.
• Analytics and settings provide supporting administrative capabilities.

• The warehouse wizard takes Zones, Aisles, Racks, and Bins as inputs, generates a nested layout model, renders a visual preview, then flattens the model into location records for a bulk POST to /inventory/locations/bulk.
• It also persists the layout configuration for future editing.
• Example hierarchy_path: WH01-Z01-A01-R01-B01

• Reserved stock moves are exposed as pending pick tasks.
• Warehouse managers assign tasks to WAREHOUSE_STAFF.
• Picked items in DONE / TRANSIT state become packing candidates.
• Packing associates a box number with the picked items.

• Transfers expose Pending → In Transit → Received progression.
• Destination routing is bound to the logged-in tenant_id.
• Putaway scans the TRANSIT zone and suggests empty storage bins.
• Dealer workflows can bypass bin selection and route items directly to STOCKYARD.

• Damaged Goods aggregates damaged-zone inventory with pending approvals and active transfers to derive the operational status of each item. The UI then exposes contextual actions such as RTV, Dispose, or Pick & Pack.
• Warranty Approvals allow Central WH users to approve/reject RTV and RMA requests.
• Scrap Register provides an audit-oriented record of scrapped or vendor-returned items.

• Local Locator is restricted to the current facility/tenant.
• Global Locator searches the complete branch network and resolves tenant identifiers into readable entity names.

• Central WH manager creates an RFQ.
• Approved vendors are explicitly invited.
• Vendor quotes are compared by price, lead time, and quote source.
• A selected quote is approved; backend logic generates the Purchase Order.

PO status: Issued → Accepted → In Transit → Received

• CSV bulk import accelerates serialized/batch receiving by parsing serial numbers and manufacturing dates client-side and mapping them to the appropriate variant SKUs.

Low-stock detection cross-references inventory quants against tenant-scoped threshold rules. Administrators can move toward RFQ creation, while dealers can request stock.

• GSTIN validation requires a 15-character alphanumeric format.
• Phone validation requires 10 digits.
• Approve/Suspend status changes are exposed through ActionMenu and affect future RFQ eligibility.

• Parent SKUs are generated from brand/product information.
• Variant SKUs append attributes such as color and voltage.
• Parent and variant images are uploaded through /media/upload to S3-backed media storage.
• Fitments can be queued before the product is persisted and submitted after product creation.
• Product detail pages render variant SKU barcodes using react-barcode.

1. 1Search customer by phone.
2. 2Resolve multiple matches through a selection dropdown.
3. 3Filter product variants to items with available stock in the current warehouse.
4. 4For serialized products, require a specific available serial.
5. 5Calculate base amount, SKU-specific GST, discounts, and final total in real time.
6. 6Submit the resulting sales order payload to the backend.

Order progression: Awaiting Payment → Ready to Pack → Ready to Deliver → Fulfilled

• Pack triggers a backend transaction and Delivery Challan PDF generation.
• Deliver triggers backend generation of invoices and warranties.
• Payment modal supports partial/full payments and balance calculation.

• Service intake follows a three-step wizard: customer identification, owned EV asset retrieval, and complaint capture.
• The execution workbench checks warranties for the relevant VIN or part serial. When an ACTIVE warranty is applicable, the UI can apply warranty billing logic and zero labor/parts base amounts.
• Serialized parts require serial selection.
• Parts GST is calculated dynamically; Labor GST is calculated at 18% in the documented UI logic.
• After closure and invoice generation, the UI transitions to payment collection.

• Administrators/finance managers can review auto-generated invoices.
• invoice_number can be manually overridden to synchronize ERP numbering with physical GST books.
• Credit Notes link refunds to the originating sales order and represent a negative financial amount.

• The Asset Lifecycle Portal accepts any supported serial identifier — Battery, Motor, or VIN — and returns movement history, current ownership, and warranty context.
• Action availability is derived from possession and state. Scrap, RTV, and Warranty Claim controls are only exposed when the asset's current location/state makes the action appropriate.

• Vehicle detail shows cached battery/motor relationships.
• AMC status is displayed.
• Install/uninstall genealogy is rendered chronologically.
• Component swaps invoke backend transactional logic that updates vehicle caches, warranty state, and RMA information.

Statuses: Active Expired Claimed Voided

• Warranty status is derived from backend flags and date logic.
• Voiding requires a reason.

• Technicians can update State of Health percentage and cycle count.
• Battery transfers coordinate current_vehicle_vin, the old vehicle's current_battery_serial, and the new vehicle's current_battery_serial.
• Scrap/Dispose routes the battery through the unified scrap endpoint and voids warranty state.

• The compatibility engine uses cascading selections to prevent invalid combinations.
• Compatible products are rendered as visual cards with badges such as OEM Standard and Guaranteed Fit.

TanStack Query is the primary server-state abstraction. Queries represent read models; mutations represent state changes; invalidation reconciles cached UI state with backend state after successful operations.

• Form state for complex drawers/modals.
• Queued fitments before product creation.
• Dynamic complaint rows in service tickets.
• Warehouse layout generation before persistence.
• Client-side aggregation and filtering where documented.
• Derived UI state such as warranty, damaged-goods, and PO step states.

Client-side calculations and derived states are for UX and presentation. Backend transactions remain authoritative for stock movement, delivery, invoice generation, warranty changes, component swaps, and other persistent domain transitions.

• 10-digit phone validation.
• 15-character GSTIN validation.
• Required serial selection for serialized inventory/products.
• Warehouse/tenant-aware stock selection.
• Entity-type-driven role assignment.
• Central Warehouse uniqueness behavior.
• Cascading fitment selections.

Axios interceptors provide a common error UX. Validation responses are parsed into field-specific messages, while authentication failures trigger a login redirect. This prevents each page from reinventing error handling.

Operations such as pack, deliver, component swaps, and inventory changes are documented as backend ACID/transactional actions. The frontend initiates these operations and then refreshes affected query state.