BUSINESS MANAGMENT

System Overview: Business Management Platform BMP is a decoupled, modern Business Management Platform designed to handle customer relationship management (CRM), inventory tracking, and order processing. The system strictly adheres to a client-server architecture, separating a highly interactive React frontend from a robust, stateless PHP backend.

1. Architectural Pattern The application utilizes a Decoupled Architecture:

Backend (API Layer): Built with Laravel 11 (PHP), serving exclusively as a RESTful API. It handles all business logic, data persistence, and authorization. Frontend (Presentation Layer): Built with Next.js (React) and TypeScript, consuming the Laravel API. It handles routing, state management, and the user interface. Communication: The frontend and backend communicate exclusively via stateless HTTP JSON requests, ensuring the backend remains completely agnostic of the presentation layer. 2. RESTful API Design The backend is engineered following strict REST principles:

Resourceful Routing: Endpoints map directly to domain entities (e.g., GET /api/v1/customers, POST /api/v1/orders). Stateless Authentication: Session cookies are bypassed in favor of Laravel Sanctum. Clients authenticate via a POST /auth/login endpoint, receive a secure Bearer token, and attach it to the Authorization header of subsequent requests. Data Validation & Error Handling: All incoming data is validated server-side using Laravel FormRequest classes. Validation failures automatically return standardized 422 Unprocessable Entity responses containing field-level error arrays, ensuring the frontend can gracefully map errors to UI inputs. Event-Driven Workflows: State mutations trigger internal events. For example, updating an order's status triggers an OrderStatusUpdated Notification class that routes updates to both the Database (for the in-app UI bell) and Mail channels asynchronously. 3. Database Schema & ORM The persistence layer utilizes a relational database managed through Laravel's Eloquent ORM and database migrations. The schema is highly normalized:

Users & RBAC: Handled via the Spatie/Laravel-Permission package. Users are mapped to specific roles (Admin, Manager, Staff) which dictate their permissions. Customers: Stores CRM data (name, email, phone, address). Has a One-to-Many relationship with Orders. Products/Services: The inventory catalog, tracking SKUs, pricing, and active status. Orders & Order Items: A complex Many-to-Many relationship implementation. An Order belongs to a Customer. The OrderItems pivot table connects Orders to Products, freezing the quantity and unit_price at the time of purchase to ensure historical financial data remains immutable even if a product's base price changes later. 4. Security & Authorization Role-Based Access Control (RBAC): Access is governed by Laravel Policies. For example, OrderPolicy intercepts requests to DELETE /orders/{id} and verifies the acting User holds the Admin role before touching the database. Route Protection: All endpoints (except login) are shielded by the auth:sanctum middleware. Frontend Guarding: The React frontend utilizes a global Context Provider (AuthContext) to track the JWT token and user state, eagerly redirecting unauthenticated users to the login screen and conditionally rendering UI elements (like the "Delete" button) based on the user's role payload. 5. Frontend Engineering TypeScript: Enforces strict typing on all API responses using custom interfaces (e.g., AppNotification, Order, Customer), catching data-shape mismatches at compile time. Component Design: Built using a modular approach with Tailwind CSS for utility-first styling. The UI emphasizes a premium glassmorphism aesthetic with responsive layouts that degrade gracefully from desktop grids to mobile-friendly drawer navigations. Resilience: Async pages implement defensive rendering, ensuring loading states and empty states (e.g., "No orders found") are displayed reliably, preventing JavaScript mapping exceptions if API responses are empty.