# AGENTS.md # Project Overview Build a fully automated auto parts e-commerce platform called: Parts using: - Laravel - React - Flowbite - TailwindCSS - MySQL The system must be scalable, modular, production-ready, lightweight, responsive, adaptive, maintainable, and optimized for performance. The platform must support advanced automotive compatibility data, dynamic technical specifications, e-commerce functionality, stock management, customer accounts, guest checkout, payments, shipping, and a complete admin panel. The system must be suitable for very large product catalogs and complex compatibility relationships. --- # Server Structure Main repository server: root@204.168.224.85 Main repository location: ~/Parts.git Production live project location: /srv/www/htdocs/Parts The live environment is automatically updated through a Git hook after pushes to: origin/main The deployment hook is already configured. Every completed feature or testing-ready change pushed to main must automatically deploy to the live environment. --- # Branch Workflow Branches: - development = local active development branch - main = stable remote branch connected to automatic live deployment - live = optional production branch if needed later ## Main Workflow Rule All coding and changes happen ONLY on the local development branch. The local machine should NEVER work directly on local main. The intended workflow is: local development branch -> push directly to remote origin/main -> automatic deployment updates live environment Main deployment command: git push origin development:main Meaning: local branch: development remote branch: origin/main This command pushes the current local development branch directly into the remote main branch without switching local branches. --- # Required Workflow 1. Work locally on development branch 2. Check current branch: git branch 3. Verify changes: git status 4. Commit changes: git add . git commit -m "Describe completed work" 5. Push local development branch directly into remote main: git push origin development:main 6. Verify deployment succeeded 7. Verify live environment works correctly --- # Deployment Rules After important feature completion: 1. Ensure migrations are safe 2. Ensure build compiles correctly 3. Ensure no syntax errors exist 4. Ensure environment compatibility 5. Push stable changes to origin/main 6. Verify live deployment updates correctly 7. Verify production pages load properly 8. Verify database migrations succeed safely 9. Verify assets compile correctly Common commands: composer install php artisan migrate php artisan optimize:clear npm install npm run build Do not assume deployment succeeded without verification. --- # Core Requirements The platform must support: - Auto parts catalog - Vehicle compatibility system - OEM and alternative part numbers - Dynamic technical specifications - Physical specifications - Customer accounts - Guest checkout - Orders - Payments - Shipping - Inventory management - Admin panel - Product tags - Search and filtering - SEO optimization - Responsive design - Performance optimization --- # Tech Stack Backend: - Laravel 12 - PHP 8.3 - MySQL Frontend: - React - Vite - TailwindCSS - Flowbite --- # Architecture Rules - Keep controllers thin - Move business logic into services - Use Form Requests for validation - Use Eloquent relationships correctly - Avoid duplicated business logic - Reuse components whenever possible - Keep frontend components modular - Separate UI logic from business logic - Use migrations for database changes - Use policies and middleware for permissions - Never hardcode credentials or secrets - Prefer environment variables and configuration files --- # Simplicity and Code Quality Rules The project must stay simple, clean, and maintainable. Codex must: - Follow Laravel standards - Follow React standards - Follow TailwindCSS standards - Follow Flowbite standards - Follow MySQL best practices - Use framework conventions instead of custom complicated solutions - Prefer simple solutions over over-engineered architecture - Keep code readable and easy to maintain - Avoid unnecessary abstractions - Avoid unnecessary packages - Avoid custom code when the framework already provides a good solution - Keep files organized by responsibility - Keep functions small and clear - Keep components reusable but not overly generic - Write production-quality code - Avoid quick hacks - Avoid duplicated logic - Avoid breaking existing behavior Quality requirements: - Clear naming - Consistent formatting - Proper validation - Proper error handling - Proper database relationships - Proper indexes where needed - Secure defaults - Lightweight implementation - Responsive UI - Easy future expansion Main rule: Simple first. Standard first. Quality always. --- # Auto Parts Catalog Each part must support: - Name - Brand - Category - Subcategory - System type - OEM part number - Alternative numbers - Supplier numbers - Internal SKU - Barcode / EAN - Description - Technical specifications - Physical specifications - Vehicle compatibility - Engine compatibility - Transmission compatibility - Product images - Stock quantity - Condition: - new - used - refurbished - Status: - active - draft - archived - out_of_stock - Price - Discount price - Tags --- # Vehicle Compatibility System The system must support many-to-many compatibility relationships. One part can fit many vehicles. One vehicle can use many parts. Vehicle data should include: - Make - Model - Generation - Body type - Year from - Year to - Engine code - Engine size - Fuel type - Horsepower - Transmission type - Drive type - Chassis code Example: Part: VANOS motor Compatible vehicle: BMW 316ti Compact E46 Engine: N42B18A Years: 2001-2005 Transmission: Manual / Automatic if applicable Compatibility data must be searchable and filterable. --- # Part Numbers Each part must support multiple number types: - OEM number - Original manufacturer number - Alternative number - Replacement number - Supplier number - Internal SKU - Aftermarket number All part numbers must be searchable. Example: OEM: 11367500032 Alternative: 11367509295 SKU: BMW-E46-N42-VANOS-001 --- # Dynamic Specifications System The platform must support dynamic specifications depending on product category. Examples: For VANOS motor: - Pins - Voltage - Connector type - Material - Mounting type - Length - Width - Height - Weight For brake disc: - Diameter - Thickness - Bolt holes - Ventilated For sensor: - Pins - Sensor type - Cable length - Connector shape Requirements: - Admin can create custom specification fields - Specifications vary by category - Specifications can be searchable - Specifications can be filterable Recommended tables: - specification_groups - specification_fields - product_specification_values --- # Categories and Systems Products must be organized by: - Main category - Subcategory - Vehicle system - Tags Vehicle systems examples: - Engine - Transmission - Suspension - Brakes - Steering - Cooling - Fuel system - Exhaust - Electrical - Sensors - Interior - Exterior - Lighting - Air conditioning - Ignition - Turbo / intake - ECU / modules --- # Search and Filters The system must support advanced search. Search by: - Product name - OEM number - Alternative number - SKU - Brand - Vehicle make - Vehicle model - Engine code - Category - Tags - Specifications Filters: - Make - Model - Year - Engine - Transmission - Brand - Condition - Category - Price - Stock status - System type - Technical specifications --- # Customers and Guests Support: ## Registered users - Registration - Login - Saved addresses - Order history - Wishlist - Saved vehicles - Invoices - Returns ## Guest users Guests must be able to: - Browse products - Add products to cart - Checkout without registration - Track orders using email + order number --- # Customer Vehicles Registered users can save vehicles. Fields: - Make - Model - Year - Engine - Engine code - Transmission - VIN optional The system should recommend compatible parts for saved vehicles. --- # Cart and Checkout Cart must support: - Guest carts - Logged-in carts - Quantity changes - Stock validation - Discount codes - Shipping calculations - Payment method selection - Order notes Checkout fields: - Customer name - Email - Phone - Billing address - Shipping address - Delivery method - Payment method - Invoice details --- # Orders Order statuses: - pending - confirmed - awaiting_payment - paid - processing - packed - shipped - delivered - cancelled - returned - refunded Each order must store: - Customer snapshot - Product snapshot - Prices snapshot - SKU snapshot - OEM numbers snapshot - Shipping method - Payment method - Tracking number - Internal notes Never rely on current product data for old orders. --- # Payments Supported methods: - Cash on delivery - Bank transfer - Card payment - Stripe optional - PayPal optional Payment statuses: - unpaid - pending - paid - failed - refunded Payment methods must be configurable from admin panel. Never store raw card data. --- # Shipping Shipping methods: - Courier delivery - Office pickup - Local pickup - Free shipping - Fixed shipping - Weight-based shipping later Orders must support: - Shipping provider - Tracking number - Shipping price - Delivery status --- # Admin Panel Admin panel must support management of: - Products - Categories - Brands - Vehicle makes - Vehicle models - Generations - Engines - Transmissions - Compatibility - Specifications - Orders - Customers - Guest orders - Payments - Shipping methods - Discounts - Tags - Images - Settings - Inventory --- # Git Safety Rules - Never commit .env - Never commit vendor/ - Never commit node_modules/ - Never commit generated secrets - Never force push unless explicitly approved - Never break deployment hooks - Never manually edit production deployment files - Never assume deployment succeeded without verification --- # Main Principle Simple workflow. Stable deployment. Development branch stays local. Remote main controls live deployment. Quality first. Framework standards first.