Kemotives Laravel: The High-Performance Engine Powering Kenya's Vehicle Marketplace

What Is Kemotives Laravel?

Kemotives Laravel is the enterprise REST API backend powering the Kemotives automotive marketplace in Kenya. It acts as the central engine serving both the buyer-facing web client and administrative dealer dashboards, providing a robust, scalable architecture for vehicle listings, automotive accessory commerce, dealer subscription tiers, and financial transactions.

Engineered with PHP 8.3 and Laravel 13, the platform manages complex automotive data models, ensures security through tokenized authentication and KYC identity verification, and introduces conversational search for car buyers across Kenya.

Tech Stack

Layer	Technology
Backend Framework	Laravel 13 (laravel/framework ^13.8) on PHP 8.3
Authentication	Laravel Sanctum (laravel/sanctum ^4.0)
Media & Storage	Cloudinary PHP SDK (cloudinary/cloudinary_php ^3.1)
Payments & Webhooks	M-Pesa Daraja API & Paystack with Signature Verification
Database & ORM	Relational Database (MySQL / PostgreSQL) with Eloquent ORM
Natural Language Engine	Custom NLP Query Parser with Kenyan Automotive Heuristics
Testing & Code Quality	Pest PHP 4 (pestphp/pest ^4.7), PHPUnit 12, Laravel Pint

Architecture & Features

The API follows clean architectural separation with dedicated controllers, Eloquent models, custom middleware, and form request validations.

1. Authentication & Token Management

User and seller authentication is managed with Laravel Sanctum, offering lightweight, secure API token issuance for Single Page Applications and mobile consumers:

• Auth Endpoints: Secure registration, login, token refresh, and logout routines.
• Password Recovery: Tokenized forgot-password and reset-password flows.
• Role & Scope Segregation: Distinct capabilities for marketplace buyers, registered sellers/dealers, and platform administrators.

2. Vehicle Catalog & Multi-Attribute Search Engine

Automotive listings require intricate specifications to enable effective filtering. The VehicleController, Car, and CarImage models handle:

• Rich Specifications: Year of manufacture (YOM), make, model, price (in KES), mileage, condition (New, Foreign Used, Local Used), transmission, fuel type, and drive system (4WD, 2WD, AWD).
• Listing Lifecycle: Draft, active, and archived states, with seller-level listing limit checks based on subscription tiers.
• Analytics & Engagement: Dedicated endpoint (/product/{slug}/track-view) to capture vehicle page views and buyer interest without skewing search cache.
• Client-Tolerant Routing: Dual route definitions (/publicproducts and /publicProducts) to ensure zero broken links across varying frontend client versions.

3. "Kemo" — Conversational AI Vehicle Search Agent

A standout capability of the backend is Kemo, an intelligent vehicle assistant implemented in AgentController:

User Query: "Show me automatic Toyota SUVs in Nairobi under 3M"
   │
   ▼
[NLP Parsing Engine] ── extracts:
  • Make: Toyota
  • Category: SUV
  • Transmission: Automatic
  • Location: Nairobi
  • Price Max: 3,000,000 KES
   │
   ▼
[Dynamic Query Builder] ── filters active inventory with images
   │
   ▼
[Response Builder] ── returns matching cars, conversational summary,
                     and smart follow-up suggestions

• Natural Language Parsing: Regular expression heuristics parse buyer intent, recognizing price short-forms (2M, 500k), Kenyan towns (Nairobi, Mombasa, Nakuru, Kisumu), and vehicle body styles.
• Smart Suggestions: Suggests contextual queries if zero results are found (e.g., broadening price thresholds or suggesting popular alternative models).

4. Dual-Gateway Payments & Idempotent Webhooks

Monetization for dealership storefronts relies on subscription packages. The backend integrates both M-Pesa and Paystack:

• Idempotency Safeguards: The PaymentWebhookController ensures transactions cannot be processed twice. If a webhook with an existing txnId is received, it returns success immediately without re-crediting the account.
• Signature Verification: Custom middleware (VerifyWebhookSignature) inspects payload hashes to prevent spoofed callbacks.
• Automatic Subscription Lifecycle: Validated payments instantly activate the corresponding dealer subscription tier.

5. Dealer KYC & Seller Verification Pipeline

To maintain buyer trust and eliminate marketplace fraud, the API includes a Know Your Customer (KYC) pipeline:

• Document Submission: Sellers submit business registration documentation and identity credentials via /kyc/submit.
• Administrative Review: Admins review, approve, or reject seller submissions with clear audit trails.
• Badge & Listing Privileges: Verified sellers unlock verified dealer badges on the marketplace frontend and elevated listing limits.

6. Auto Accessories, Automotive Blog & Community Voting

Beyond whole vehicles, the ecosystem extends into aftermarket parts and enthusiast content:

• Accessories Store: Full CRUD and public querying for car parts, accessories, and maintenance supplies.
• Editorial Blog Engine: Integrated article management with slug-based routing and view count tracking.
• Community Upvoting: Interactive voting system (/blogs/{blogId}/vote) allowing the car enthusiast community to upvote helpful guides and automotive reviews.

What I Learned / Engineering Decisions

1. Idempotent Webhook Design: Payment webhooks from payment gateways can arrive multiple times due to network retries. Designing the webhook handler to be strictly idempotent around txn_id guarantees consistent financial state.
2. Database Driver Agnostic Search: By checking the active database connection driver (DB::connection()->getDriverName() === 'pgsql' ? 'ilike' : 'like'), the search queries run seamlessly on both local PostgreSQL setups and production MySQL instances without syntax breaks.
3. Resilient API Contracts: Frontend frameworks and third-party consumers occasionally send conflicting casing. Supporting dual route variations for high-traffic listing endpoints eliminated unneeded 404 errors during client refactoring.

View on GitHub →