Cartxis Mobile App

Open Source Flutter eCommerce App for iOS & Android

cartxis.com • Backend Repository • Demo v1.0.0

Overview

Cartxis is a free, open source mobile shopping app built ̌̌with Flutter. It connects to the Cartxis web backend which provides all the API, admin panel, product management, orders, and payment processing.

⚠️ The mobile app requires the Cartxis web backend to be running first. All data — products, users, orders, payments, settings — comes from the API. Set up the backend before running the mobile app.

Requirements

Mobile App

Tool	Version
Flutter SDK	3.x
Dart	3.x
Xcode	15+ (iOS builds)
Android Studio	Latest (Android builds)
Android SDK	API 24+
CocoaPods	Latest (iOS dependencies)

Backend Server

Requirement	Version
PHP	8.2+
Composer	2.x
Node.js	18.x+
NPM	9.x+
MySQL	8.0+

Step 1 — Set Up the Backend

Everything depends on the Cartxis web backend. Set it up first.

Backend Repository: https://github.com/wontonee/cartxis

Option A — Quick Install (Recommended)

The fastest way to get a production-ready store:

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

The interactive installer handles database setup, admin account creation, migrations, seeders, and asset publishing automatically.

Option B — Development Install (Git Clone)

Use this method if you want to contribute to the backend or customise it.

# 1. Clone the repository
git clone https://github.com/wontonee/cartxis.git
cd cartxis

# 2. Install PHP dependencies
composer install

# 3. Install Node.js dependencies
npm install

# 4. Set up your environment file
cp .env.example .env
php artisan key:generate

# 5. Create a MySQL database, then update .env:
#    DB_DATABASE, DB_USERNAME, DB_PASSWORD

# 6. Run the Cartxis installer (migrations, seeders, admin setup)
php artisan cartxis:install

# 7. Build frontend assets
npm run build

# 8. Start the development server
php artisan serve

Once the backend is running, note your API base URL (e.g. https://yourdomain.com).

Payment Gateway Configuration

All four payment gateways are configured from the Admin Panel → Settings → Payment Methods. No .env changes are needed for payment keys — enter them directly in the admin panel.

Gateway	Admin Panel Setting
Stripe	Settings → Payment Methods → Stripe
Razorpay	Settings → Payment Methods → Razorpay
PhonePe	Settings → Payment Methods → PhonePe
PayPal	Settings → Payment Methods → PayPal

Production Deployment Checklist

Before going live, run the following on your server:

# Set production environment in .env
APP_ENV=production
APP_DEBUG=false

# Optimise Laravel
composer install --optimize-autoloader --no-dev
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan storage:link

Set up a queue worker (Supervisor recommended) — required for email and async jobs

Add the scheduler cron to run every minute:

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

Point your web server (Nginx/Apache) document root to the public/ directory

Step 2 — Set Up the Mobile App

Clone the repository

git clone https://github.com/wontonee/cartxis-mobile.git
cd cartxis-mobile

Install dependencies

flutter pub get

Configure the API URL

Open lib/core/config/api_config.dart and update the base URLs:

// For development
static const String _iosBaseUrl     = 'https://your-local-domain.test';
static const String _androidBaseUrl = 'https://10.0.2.2'; // Android emulator host gateway

// For production
static const String productionBaseUrl = 'https://yourdomain.com';

// Set to true for production
static const bool isProduction = true;

iOS Simulator: Add your local domain to /etc/hosts on your Mac and use it directly. Android Emulator: Use 10.0.2.2 as the IP (maps to your Mac/PC localhost). The app automatically passes the correct Host header for nginx vhost routing.

Install iOS pods

cd ios && pod install && cd ..

Run the app

# Development
flutter run

# Release mode
flutter run --release

Payment Gateways

Cartxis supports 4 payment gateways — all configured from the backend admin panel. No changes are needed in the mobile app code.

Gateway	Status	Supported Methods
Stripe	✅ Supported	Credit / Debit Cards, Apple Pay (iOS)
Razorpay	✅ Supported	UPI, Cards, Net Banking, Wallets
PhonePe	✅ Supported	UPI Payments
PayPal	✅ Supported	PayPal Checkout (WebView)

Configure your gateway API keys in the backend admin panel under Settings → Payment Methods. The mobile app fetches the active configuration automatically at checkout.

Features

🛍️ Shopping

Browse products by category with featured, new arrivals, and on-sale sections
Product search and filtering
Product detail with image gallery, variants, and stock status

🛒 Cart & Checkout

Add/remove items, update quantities
Full address management with multiple saved addresses
Choose from available payment gateways at checkout
Order summary with shipping calculation

👤 Account & Profile

Register, Login, Forgot Password with email reset
Profile management with avatar upload
Order history and detailed order tracking
Wishlist — save and manage favourite products
Dark mode support
Secure account deletion (password-confirmed)

⚙️ Admin-Driven Configuration

Login screen logo loaded from backend settings (/api/v1/app/settings)
Payment methods enabled or disabled from admin panel — no app update needed
All product data, pricing, inventory and banners managed from the backend

Project Structure

lib/
├── core/
│   ├── config/          # API config, environment settings
│   ├── constants/       # Colours, strings, sizes, text styles
│   ├── network/         # HTTP client, API exception handling
│   ├── services/        # Heartbeat, connectivity
│   └── theme/           # App theme
├── data/
│   ├── models/          # User, Product, Order, Cart, Wishlist models
│   └── services/        # Auth, Product, Cart, Order, Wishlist, Payment, AppSettings
├── presentation/
│   └── screens/
│       ├── auth/        # Login, Register, Forgot Password
│       ├── home/        # Home, Featured, Categories
│       ├── product/     # Product listing, detail
│       ├── cart/        # Cart, Checkout
│       ├── orders/      # Order history, Order detail
│       ├── wishlist/    # Wishlist
│       ├── profile/     # Profile, Settings, Delete Account
│       └── main/        # Bottom navigation shell
└── routes/              # Named route definitions

API Connectivity

The app uses a heartbeat system to stay in sync with the backend:

Endpoint	Purpose
`POST /api/v1/system/api-sync/heartbeat`	Sent on app start and resume
`GET /api/v1/app/settings`	Admin-configured logo and settings
`DELETE /api/v1/auth/account`	Authenticated account deletion

All authenticated endpoints use a Bearer token stored securely in SharedPreferences.

Building for Release

Android — Google Play Store

flutter build appbundle --release

Output: build/app/outputs/bundle/release/app-release.aab

Upload the .aab to the Google Play Console.

Application ID: com.cartxis.app

The signing keystore credentials are stored in the important/ folder (git-ignored — keep a secure backup).

iOS — App Store

flutter build ipa --release

Open ios/Runner.xcworkspace in Xcode to archive and upload to App Store Connect.

Play Store / App Store — Account Deletion URL

Google Play and Apple App Store require apps that allow account creation to provide an account deletion option. The Cartxis backend includes a dedicated account deletion page that satisfies this requirement.

Account Deletion URL: https://yourdomain.com/account-deletion

Use this URL in:

Google Play Console → App content → Data safety → Account deletion
App Store Connect → App Privacy → Account deletion URL

The mobile app also provides in-app account deletion under Profile → Delete Account, which requires password confirmation.

Development Notes

Set isProduction = false in api_config.dart for local development
Self-signed SSL certificates are bypassed automatically in development mode
Android emulator connectivity uses 10.0.2.2 + Host header for nginx vhost routing
All debug print() statements have been removed from production code

License

This project is open source under the MIT License. See the LICENSE file for details.

Support

Website: https://cartxis.com
Email: dev@wontonee.com
Backend Repo: https://github.com/wontonee/cartxis

Built with ❤️ — cartxis.com

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Cartxis Mobile App

Overview

Requirements

Mobile App

Backend Server

Step 1 — Set Up the Backend

Option A — Quick Install (Recommended)

Option B — Development Install (Git Clone)

Payment Gateway Configuration

Production Deployment Checklist

Step 2 — Set Up the Mobile App

Clone the repository

Install dependencies

Configure the API URL

Install iOS pods

Run the app

Payment Gateways

Features

🛍️ Shopping

🛒 Cart & Checkout

👤 Account & Profile

⚙️ Admin-Driven Configuration

Project Structure

API Connectivity

Building for Release

Android — Google Play Store

iOS — App Store

Play Store / App Store — Account Deletion URL

Development Notes

License

Support

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Cartxis Mobile App

Overview

Requirements

Mobile App

Backend Server

Step 1 — Set Up the Backend

Option A — Quick Install (Recommended)

Option B — Development Install (Git Clone)

Payment Gateway Configuration

Production Deployment Checklist

Step 2 — Set Up the Mobile App

Clone the repository

Install dependencies

Configure the API URL

Install iOS pods

Run the app

Payment Gateways

Features

🛍️ Shopping

🛒 Cart & Checkout

👤 Account & Profile

⚙️ Admin-Driven Configuration

Project Structure

API Connectivity

Building for Release

Android — Google Play Store

iOS — App Store

Play Store / App Store — Account Deletion URL

Development Notes

License

Support