Cartxis — Open Source Laravel eCommerce Platform

A modern, extensible eCommerce platform built with Laravel 13, Inertia.js, Vue 3.5, and TypeScript. Cartxis provides a complete solution for building online stores with a powerful admin panel, flexible theme system, and modular architecture.

✨ Features

🛍️ Shop Features

Product Management — Complete product catalog with variants, attributes, and inventory tracking
Shopping Cart — Real-time cart with session persistence and guest checkout support
Multi-Payment Gateway — Stripe, Razorpay, PayPal, PhonePe, and PayUMoney support
Order Management — Comprehensive order tracking and lifecycle management
Customer Accounts — Registration, authentication, profile, and order history
Theme System — Flexible theme architecture with easy customization

🎛️ Admin Features

Dashboard — Analytics and key insights at a glance
Product Management — Products, categories, brands, attributes, and variants
Order Processing — Complete order lifecycle with status management
Customer Management — Profiles, addresses, and notes
Settings — Store configuration, payment methods, shipping rates, and tax rules
AI Agents — Create and manage custom AI agents for commerce workflows
Email Templates — Customizable transactional email templates
CMS & UI Editor — Visual drag-and-drop page builder with 32+ block types, global regions, reusable saved blocks, and responsive live preview
Reports — Sales, customer, and inventory reporting
Maintenance Mode — Built-in maintenance banner and system controls

💳 Payment Gateways

Gateway	Status
Stripe	✅ Supported
Razorpay	✅ Supported
PayPal	✅ Supported
PhonePe	✅ Supported
PayUMoney	✅ Supported

📱 Mobile App

The Cartxis Mobile App is live and open source! Download it or explore the source:

Platform	Link
Android (Google Play)	Download on Google Play
Source Code	github.com/wontonee/cartxis-mobile

The app is powered by a full REST API and supports:

Authentication and customer accounts
Product catalog, search, and categories
Cart, checkout, and order management
Wishlist and reviews
Store sync and banners

🗑️ Google Play / App Store — Account Deletion URL

Google Play Store (and Apple App Store) require apps that support account creation to provide a publicly accessible account deletion page as part of their Data Safety policy.

Cartxis includes this page out of the box. When submitting your app, use the following URL pattern:

https://yourdomain.com/account-deletion

Example: https://shop.example.com/account-deletion

This page:

Is publicly accessible (no login required)
Explains step-by-step how users can delete their account from within the app
Lists what data is permanently deleted (profile, addresses, wishlist, cart, tokens)
Discloses what is retained (anonymized order records for accounting, 7-year minimum)
Provides an email contact ([email protected]) for users who cannot log in

In the Google Play Console → App content → Data safety, paste this URL in the "Delete account URL" field.

🔧 Technical Features

Modular Architecture — Package-based structure for easy extension
MySQL 8.0+ — Optimised relational database layer
Modern Frontend — Vue 3 with TypeScript and Tailwind CSS
Inertia.js — SPA-like experience without API complexity
Two-Factor Authentication — Enhanced security with 2FA
Email Verification — Built-in email verification workflow
Fortify Integration — Laravel Fortify for authentication

📋 Requirements

Requirement	Version
PHP	8.3 or higher
Composer	2.x
Node.js	18.x or higher
NPM	9.x or higher
MySQL	8.0 or higher

Required PHP extensions: OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath

🚀 Quick Install via Composer

The fastest way to get Cartxis running:

composer create-project cartxis/cartxis my-store
cd my-store
php artisan cartxis:install

The interactive installer will guide you through:

Database configuration (with live connection test)
Theme directory API key registration (for Browse Themes / one-click installs)
Admin account creation (name, email, and password)
Migrations and seeders
Building frontend assets automatically

Once complete, the installer displays your admin panel URL, email, and password.

Theme directory (Browse Themes)

During install, Cartxis registers a free API key with the official theme catalog at https://cartxis.com/api. This enables Admin → Appearance → Browse Themes for one-click theme installs.

If registration fails during install (offline server, firewall, etc.):

# Ensure .env uses the non-www URL
CARTXIS_THEME_DIRECTORY_URL=https://cartxis.com/api

php artisan theme:directory:register

See docs/THEMES.md for installing themes, customization, and troubleshooting.

If you see blank pages or asset errors after the setup wizard, the frontend build may not have completed yet. Fix it by running:
npm run build
php artisan optimize:clear
# or if you use Yarn:
yarn build

🛠️ Installation (Development / Git Clone)

Use this method if you are contributing to or developing on Cartxis.

1. Clone the Repository

git clone https://github.com/cartxis/cartxis.git
cd cartxis

2. Install Dependencies

composer install
npm install

3. Environment Setup

cp .env.example .env
php artisan key:generate

4. Database Setup

Create a MySQL database:

CREATE DATABASE cartxis CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Update your .env file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cartxis
DB_USERNAME=your_username
DB_PASSWORD=your_password

5. Run the Installer

php artisan cartxis:install

Or manually run migrations and seed:

php artisan migrate --seed

Note: When seeding manually, provide admin credentials via environment variables:
CARTXIS_ADMIN_NAME="Admin" \
CARTXIS_ADMIN_EMAIL="[email protected]" \
CARTXIS_ADMIN_PASSWORD="yourpassword" \
php artisan db:seed

6. Build Frontend Assets

Development (watch mode):

npm run dev

Production build:

npm run build

7. Start the Server

php artisan serve

Visit http://localhost:8000 for the storefront and http://localhost:8000/admin/login for the admin panel.

⚙️ Configuration

Email Configuration

Email (SMTP) settings are configured directly in the Admin Panel — no .env changes required.

Log in to Admin → Settings → Email Settings
Enter your SMTP host, port, username, password, and encryption type
Set your "From" name and address
Send a test email to verify the configuration

Payment Gateway Setup

All payment gateway credentials are configured directly in the Admin Panel — no .env changes required.

Log in to Admin → Settings → Payment Methods
Select the gateway you want to enable (Stripe, Razorpay, PayPal, PhonePe, or PayUMoney)
Enter your API keys and credentials in the provided fields
Toggle the gateway to Active

Your credentials are stored securely in the database and managed entirely through the admin interface.

Store Settings

Configure your store through the admin panel:

Settings → Store Configuration — name, currency, timezone
Settings → Payment Methods — enable/disable gateways
Settings → Shipping — shipping rates and zones
Settings → Tax Rules — tax configuration

📦 Package Structure

packages/Cartxis/
├── Admin/          # Admin panel — controllers, views, assets
├── Cart/           # Shopping cart management
├── CMS/            # Content pages and blocks
├── Core/           # Core utilities, installer command, service providers
├── UIEditor/       # Visual drag-and-drop page builder
├── Customer/       # Customer profiles and authentication
├── Marketing/      # Promotions, coupons, and tools
├── PayPal/         # PayPal payment integration
├── PayUMoney/      # PayUMoney payment integration
├── PhonePe/        # PhonePe payment integration (SDK bundled)
├── Product/        # Product catalog, variants, attributes
├── Razorpay/       # Razorpay payment integration
├── Reports/        # Sales, inventory, and customer reports
├── Sales/          # Orders and sales management
├── Settings/       # System and store settings
├── Setup/          # First-run setup wizard
├── Shop/           # Frontend storefront
├── Stripe/         # Stripe payment integration
└── System/         # System health and utilities

🖌️ Visual Page Builder (UI Editor)

Cartxis ships with a powerful visual drag-and-drop page builder that lets you design storefront pages and reusable regions without writing code.

Layout Hierarchy

Layouts are a three-level tree stored as JSON:

Page → Sections → Columns → Blocks

Sections — Full-width rows with configurable background colour, padding, and full-width toggle
Columns — Responsive 12-column grid; presets: 1, 2, 3, 4 columns · 2/3+1/3 · 1/3+2/3
Blocks — Content units dropped into columns; each block type has its own settings panel

32 Built-in Block Types

Category	Block Types
Layout	`spacer`, `divider`
Text & Content	`heading`, `text`, `image`, `button`, `video`, `form`, `table`, `card`, `html`, `code`, `accordion`, `tabs`, `icon_box`, `counter`, `social_links`, `author_card`, `share_buttons`
Commerce	`hero`, `slider`, `products_grid`, `categories_grid`, `newsletter`, `pricing`, `testimonials`
Blog	`post_featured`, `post_list`, `post_carousel`, `blog_posts_grid`
Regions	`global_region`

Global Regions

Create reusable layout areas (header, footer, sidebar, banner, section) that are embedded into any page via the global_region block. Updating a global region propagates instantly to every page that references it.

Default seeded regions: Main Header and Main Footer.

Saved (Reusable) Blocks

Save any section or individual block as a reusable template. Saved blocks appear in the block palette under the Saved tab and can be inserted into any page — ideal for promotional banners, CTA strips, or complex product grids you want to maintain consistently.

Theme Integration

The UIBlockRenderer Vue component is shared across all themes. When a published layout exists for a page, it is rendered visually via the block renderer; if no published layout exists the platform falls back gracefully to raw HTML, preserving backward compatibility.

🎨 Themes & Template Zone

Storefront themes are templates under templates/storefront/{category}/{slug}/. The default cartxis-default theme is bundled; additional themes (e.g. Dmart Electronics) install from the remote catalog.

Browse & install themes

Admin → Appearance → Browse Themes
Choose a category, click Install (optionally Activate)
Cartxis publishes assets, clears caches, and rebuilds frontend bundles automatically

Customize the active theme

Admin → Appearance — colors, typography, layout (sidebar, header), features
Admin → UI Editor — block-based homepage (non-native themes)
Appearance → Features — native homepage sections (themes with built-in homepages)

Common commands

php artisan theme:list
php artisan template:install dmart-electronics --activate
php artisan theme:discover
php artisan theme:directory:register
php artisan optimize:clear && npm run build   # manual recovery

Theme troubleshooting

Issue	Quick fix
Broken CSS / missing sidebar after theme change	Hard-refresh browser; re-activate theme in admin or run `optimize:clear` + `npm run build`
“Template page not found”	`npm run build` (theme pages are bundled at build time)
Theme directory key failed on install	Set `CARTXIS_THEME_DIRECTORY_URL=https://cartxis.com/api` (no `www`), run `theme:directory:register`
Remote install broke `npm run build`	`php artisan theme:discover` (removes macOS ZIP junk), then `npm run build`

Full guide: docs/THEMES.md · API reference: docs/THEME_DIRECTORY_API.md

🎨 Theme Development

Storefront templates live under templates/storefront/{category}/{slug}/. The default template is templates/storefront/general/cartxis-default/.

Creating a Custom Template

cp -r templates/storefront/general/cartxis-default templates/storefront/general/your-theme-name

Update config/theme.php (or activate via Admin → Appearance):

'default' => 'your-theme-name',

Customise:

Pages: templates/storefront/general/your-theme-name/resources/views/pages/
Components: templates/storefront/general/your-theme-name/resources/views/components/
Layouts: templates/storefront/general/your-theme-name/resources/views/layouts/
Demo data: templates/storefront/general/your-theme-name/data/theme-data.json

Discover and register templates:

php artisan theme:discover
php artisan theme:import-data cartxis-default
npm run build    # required after adding/changing theme Vue pages

After installing or activating any theme in admin, Cartxis runs discover, optimize:clear, and npm run build automatically when CARTXIS_THEME_REBUILD_ASSETS=true (default).

🧪 Running Tests

# Run all tests
./vendor/bin/pest

# Feature tests only
./vendor/bin/pest tests/Feature

# With coverage
./vendor/bin/pest --coverage

🚢 Deployment

Production Checklist

Set APP_ENV=production and APP_DEBUG=false in .env
composer install --optimize-autoloader --no-dev
npm ci && npm run build
php artisan migrate --force
php artisan theme:discover
php artisan config:cache
php artisan route:cache
php artisan view:cache

Set file permissions:

chmod -R 755 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Configure your web server (Nginx/Apache) with document root pointing to public/
Set up an SSL certificate
Configure queue workers and the task scheduler

After installing or activating a theme on production, run php artisan optimize:clear and npm run build — or activate the theme from admin (triggers this automatically). See docs/THEMES.md.

Queue Workers

php artisan queue:work

Use Supervisor in production to keep queue workers running.

Scheduler

Add to crontab:

* * * * * cd /path-to-cartxis && php artisan schedule:run >> /dev/null 2>&1

🛠️ Developer Notes

Code Style

PHP: PSR-12 standard — ./vendor/bin/phpcs
TypeScript/JavaScript: ESLint — npm run lint

Clearing Caches

php artisan optimize:clear

Creating an Extension

See EXTENSION-DEVELOPMENT-GUIDE.md for the full guide on building Cartxis extension packages.

🤝 Contributing

Contributions are welcome!

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

Please follow PSR-12 for PHP, write tests for new features, and update documentation as needed.

📞 Support

Channel	Link
Website	https://www.cartxis.com
Email	[email protected]
Issues	GitHub Issues
Discussions	GitHub Discussions

Documentation

Guide	Description
docs/THEMES.md	Install, activate, customize & troubleshoot themes
docs/THEME_DIRECTORY_API.md	Remote theme catalog API & env vars
docs/USER_GUIDE.md	Full admin user manual
docs/QUICK_REFERENCE.md	Developer commands & architecture
docs/ARCHITECTURE.md	Package map & data flows
docs/UPGRADE.md	Version upgrades

For billing, licensing, or partnership enquiries, contact us at [email protected].

🗺️ Roadmap

✅ Completed

Product management (variants, attributes, inventory)
Shopping cart with guest checkout
Order management — invoices, shipments, credit memos, transactions
Customer accounts and profiles
Wishlist
Reviews
Newsletter
Multi-payment gateway (Stripe, Razorpay, PayPal, PhonePe, PayUMoney)
CMS — pages, content blocks, and visual page builder (UI Editor with 32+ block types, global regions, saved blocks, live preview)
Media management
Email templates (customizable transactional emails)
Reports — sales, customer, and inventory
Flexible theme system
Maintenance mode
Extensions system
Backup and cache management
Tax management (classes, rates, rules, zones)
Shipping methods and delivery settings
Shiprocket integration
AI settings and product AI
Demo data (Electronics, Fashion, Kirana, Retail)
Data migration (WooCommerce, Bagisto)
REST API for mobile app
Mobile app — Android (Google Play) · Open source
Interactive CLI installer (php artisan cartxis:install)
Composer create-project support

🔜 Upcoming

iOS mobile app
Two-factor authentication (2FA)
Multi-vendor marketplace
Subscription products
Advanced SEO tools
Multi-language support (i18n)
Advanced analytics dashboard
Integration marketplace

📝 License

Cartxis is open-source software licensed under the MIT License.

Made with ❤️ by the Wontonee Team