• Features
• Tech Stack
• Architecture
• Getting Started
  • Prerequisites
  • Installation
  • Environment Configuration
  • Database Setup
  • Running the Application
• Project Structure
• MCP Tools
• User Roles
• API Routes
• Testing
• PWA Support
• Contributing
• License

• Product Browsing - Browse products by categories with advanced filtering
• Shopping Cart - Add, update, and remove items from cart
• Secure Checkout - Complete checkout process with order confirmation
• Order Tracking - View order history and track order status
• User Authentication - Register, login, and manage profile
• Two-Factor Authentication - Enhanced security with 2FA support

• Dashboard Analytics - Real-time metrics, sales trends, and KPIs
• Product Management - CRUD operations for products with image uploads
• Category Management - Organize products into hierarchical categories
• Inventory Management - Track stock levels and low stock alerts
• Order Management - View, update, and manage customer orders

• Liquid Glass Design - Modern glassmorphism aesthetic with gradients
• GSAP Animations - Smooth micro-interactions and transitions
• Responsive Design - Mobile-first, works on all devices
• Dark/Light Theme - Appearance customization with green color palette
• PWA Support - Install as a native app on mobile and desktop

• 29 MCP Tools - For AI agents to interact with the e-commerce platform
• Admin Tools - Product, category, inventory, and order management
• Customer Tools - Shopping, cart, and order operations
• Public Tools - Product browsing and search

The application follows Domain-Driven Design (DDD) principles with clear separation of concerns:

app/
├── Domain/                 # Business logic organized by domain
│   ├── Catalog/           # Products, Categories
│   ├── Dashboard/         # Admin analytics
│   ├── Identity/          # Users, Authentication
│   ├── Inventory/         # Stock management
│   ├── Order/             # Orders, Order Items
│   ├── Shared/            # Shared utilities
│   └── Shopping/          # Cart, Checkout
├── Http/                   # HTTP layer (Controllers, Middleware)
├── Mcp/                    # MCP Tools for AI agents
│   ├── Servers/           # MCP Server configurations
│   └── Tools/             # 29 MCP tool implementations
│       ├── Admin/         # Admin-only tools
│       ├── Customer/      # Customer tools
│       └── Public/        # Public tools
└── Models/                 # Eloquent models

Ensure you have the following installed:

• PHP >= 8.2
• Composer >= 2.x
• Node.js >= 20.x
• npm >= 10.x
• SQLite (or MySQL/PostgreSQL)

1. Clone the repository

   git clone https://github.com/yourusername/AgentCart.git
   cd AgentCart

2. Install dependencies

   composer install
   npm install

3. Run the setup script

   composer setup

   This command will:

   • Install PHP dependencies
   • Copy .env.example to .env
   • Generate application key
   • Run database migrations
   • Install npm dependencies
   • Build frontend assets

Copy the example environment file and configure it:

cp .env.example .env

Key environment variables:

# Application
APP_NAME=AgentCart
APP_URL=https://store.heygeeks.in

# Database (SQLite by default)
DB_CONNECTION=sqlite

# For MySQL, uncomment and configure:
# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=AgentCart
# DB_USERNAME=root
# DB_PASSWORD=

# Dashboard Configuration
DASHBOARD_LOW_STOCK_THRESHOLD=10
DASHBOARD_RECENT_ORDERS_LIMIT=10
DASHBOARD_SALES_TRENDS_DAYS=30

1. Run migrations

   php artisan migrate

2. Seed the database with sample data

   php artisan db:seed

   This creates:

   • Admin user: admin@example.com (password: password)
   • 5 sample customer users
   • Sample categories
   • Sample products with images
   • Sample inventory data
   • Sample orders

Development mode (recommended):

composer run dev

This starts concurrently:

• Laravel development server on https://store.heygeeks.in
• Queue worker for background jobs
• Vite dev server for hot module replacement

Or run services individually:

# Terminal 1 - Laravel server
php artisan serve

# Terminal 2 - Vite dev server
npm run dev

# Terminal 3 - Queue worker
php artisan queue:listen

Production build:

npm run build

AgentCart/
├── app/
│   ├── Actions/            # Action classes
│   ├── Concerns/           # Shared traits
│   ├── Domain/             # Domain logic (DDD)
│   ├── Http/               # Controllers, Middleware
│   ├── Mcp/                # MCP Tools & Servers
│   ├── Models/             # Eloquent models
│   └── Providers/          # Service providers
├── config/                 # Configuration files
├── database/
│   ├── factories/          # Model factories
│   ├── migrations/         # Database migrations
│   └── seeders/            # Database seeders
├── public/                 # Public assets, manifest.json
├── resources/
│   ├── css/               # Stylesheets
│   ├── js/
│   │   ├── components/    # React components (64 components)
│   │   ├── hooks/         # Custom React hooks
│   │   ├── layouts/       # Page layouts
│   │   ├── pages/         # Inertia pages
│   │   │   ├── Admin/     # Admin pages
│   │   │   ├── Customer/  # Customer pages
│   │   │   ├── auth/      # Authentication pages
│   │   │   └── settings/  # Settings pages
│   │   ├── types/         # TypeScript types
│   │   └── lib/           # Utilities
│   └── views/             # Blade templates
├── routes/                 # Route definitions
├── storage/                # File storage
└── tests/                  # Test files (74 test files)

AgentCart includes 29 MCP (Model Context Protocol) tools that allow AI agents to interact with the e-commerce platform:

To connect to the MCP server from an AI client (like Claude Desktop), use the following configuration:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://store.heygeeks.in/mcp/admin"
      ]
    }
  }
}

The MCP server uses OAuth 2.0 authentication via Laravel Passport. Follow these steps to authenticate:

1. OAuth Flow: When connecting to the MCP server, you'll be redirected to authenticate via the OAuth flow
2. Authorization: After logging in, authorize the MCP client to access your account
3. Token Exchange: The MCP client will receive an access token for subsequent requests

Available MCP Endpoints:

📖 For detailed setup instructions with Claude Desktop, ChatGPT, LM Studio, Ollama, and Moltbot, see public/mcp-guide.md.

The project includes 74 test files covering all major functionality.

Run all tests:

php artisan test

Run with code coverage:

php artisan test --coverage

Run specific test file:

php artisan test tests/Feature/ProductTest.php

Linting:

# PHP linting
composer lint

# JavaScript/TypeScript linting
npm run lint

# Format code
npm run format

AgentCart is a Progressive Web App (PWA) that can be installed on mobile devices and desktops:

• Installable - Add to home screen on iOS, Android, and desktop
• Offline Support - Basic offline functionality with service worker
• App Shortcuts - Quick access to Products, Cart, and Orders
• Native Feel - Standalone display mode without browser UI

1. Visit the site on your mobile device or desktop
2. Look for the "Install" prompt or browser's install option
3. Follow the installation instructions for your platform

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Commit your changes

   git commit -m 'Add amazing feature'

4. Push to the branch

   git push origin feature/amazing-feature

5. Open a Pull Request

• Follow PSR-12 coding standards for PHP
• Use TypeScript strictly (no any types)
• Write tests for new features
• Run linting before committing

This project is licensed under the MIT License - see the LICENSE file for details.