Introduction

OneMart Admin & Web is the back-office management panel and customer-facing storefront for the DayOneMart single-vendor e-commerce platform. Built on Laravel 12 with a Vue 3 / Inertia.js frontend, it ships as a single deployable application that serves three distinct surfaces:

• Admin Panel — Full business management interface (orders, products, users, analytics, settings)
• Customer Storefront — SEO-friendly web shopping experience served via Inertia
• REST API — Versioned JSON API consumed by the Flutter Customer App and Deliveryman App

Technology Stack

Project Folder Structure

/app
├── Console/
├── Enums/
├── Events/
├── Http/
│   ├── Controllers/
│   │   ├── Api/              ← REST API v1 controllers
│   │   ├── Payment/          ← Stripe, PayPal, Razorpay, etc.
│   │   ├── Web/              ← Inertia page controllers
│   │   ├── InstallerController.php
│   │   └── UpdaterController.php
│   ├── Middleware/
│   ├── Requests/
│   └── Resources/
├── Jobs/
├── Mail/
├── Models/
├── Services/
└── Utils/
    ├── constants.php
    ├── formatter.php
    └── translation.php

/resources/js
├── AdminPanel/               ← Admin Vue application
│   ├── Layouts/
│   ├── Pages/
│   │   ├── Analytics/
│   │   ├── Authentication/
│   │   ├── Dashboard/
│   │   ├── Food/
│   │   ├── Orders/
│   │   ├── Promotion/
│   │   ├── Reports/
│   │   ├── Settings/
│   │   └── ...
│   ├── components/
│   ├── composables/
│   └── locales/
└── StoreFront/               ← Customer web Vue application
    ├── Layouts/
    ├── Pages/
    │   ├── Homepage/
    │   ├── Menu/
    │   ├── Checkout/
    │   ├── Profile/
    │   └── ...
    ├── components/
    └── composables/

/routes
├── api/v1/
│   ├── admin.php
│   ├── customer.php
│   └── deliveryman.php
├── web/
│   ├── admin.php
│   ├── storefront.php
│   ├── installer.php
│   └── updater.php
└── payment.php

/lang          ← en, bn, hi, ar, es translations
/public        ← Document root — point domain here

System Features

Dashboard & Analytics

• Real-time business overview with live order stats and revenue counters
• Sales reports — daily, weekly, monthly, custom date range
• Category performance analytics
• User activity reports and hourly trend charts (Chart.js + ApexCharts)
• Top-selling products and revenue breakdown

1 2 3 4

Key areas of this screen

1. Business Analytics KPI cards — live totals for sales, orders, average order value, customers, employees, deliverymen, active promotions, and wallet flow.
2. Order Status Overview — a breakdown of orders by stage: Pending, Confirmed, Ready to Handover, Out for Delivery, Delivered, Failed, Cancelled, and Refunded.
3. Sales Trend — revenue over the selected period versus the previous period.
4. Order Type Breakdown — the mix of order types shown as a donut chart.

Order Management

• Full order lifecycle: Pending → Confirmed → Processing → Handover → Picked Up → Delivered
• Assign / unassign deliveryman per order
• Edit order items, delivery address, and customer notes
• Cancel orders with reason tracking
• Refund workflow — approve or reject refund requests
• Invoice generation and download (PDF)
• Payment status management
• Bulk order actions

1 2 3 4

Key areas of this screen

1. Status filters (left menu) — jump to All Orders, Pending, Confirmed, Ready to Handover, On the Way, Delivered, Cancelled, Refunded, and Refund Requests, each with a live count.
2. Search bar — find an order by ID or any related keyword.
3. Order Status column — update each order's stage inline via the dropdown (or the Confirm button on new orders).
4. Action buttons — view the order detail (eye icon) or download the invoice.

Product & Menu Management

• Product items with variations, add-ons, stock levels, and pricing
• Categories and sub-categories with images
• Labels (e.g. New, Best Seller, Veg) and Cuisines
• Menu Types (e.g. Breakfast, Lunch, Dinner)
• Bulk CSV / Excel import and export
• Toggle product availability and featured status

1 2 3 4

Key areas of this screen

1. Item info — the product thumbnail, name, and ID. Use Create New (top right) to add a product with images, pricing, variations, and add-ons.
2. Category — the category and sub-category each item belongs to.
3. Price — the selling price per item.
4. Stock & Status — inventory level and the availability toggle; row actions (view / edit / more) sit on the far right.

Marketing & Promotions

• Coupon codes with usage limits, minimum order value, and expiry
• Flash Sales — time-limited promotional campaigns with countdown timers
• Loyalty points — earn on orders, redeem at checkout, configurable rules
• Push notifications via Firebase Cloud Messaging
• Marketing tools & sales popup configuration
• Newsletter subscriber management

1 2 3 4

Key areas of this screen

1. Coupon name & code — the display name and the code customers enter at checkout.
2. Coupon info — discount type (Discount on Order, Free Shipping, Free Item, First Order), amount, and the modules it applies to.
3. Validity — how long the coupon is active (Unlimited or a countdown of days left).
4. Status & actions — enable/disable toggle plus view, edit, and delete; use Create New (top right) to add a coupon, and the Flash Sales menu for time-limited campaigns.

User Management

• Employees — CRUD, role & permission management (RBAC)
• Deliverymen — CRUD, working hours, earnings tracking
• Customers — CRUD, wallet balance, order history, bulk actions
• Wallet transactions overview

Website & Content

• Page builder for About, Privacy Policy, Terms & Conditions, Refund, Cancel Policy
• Blog management (create, publish, draft)
• FAQ management
• Social media link configuration
• Homepage banner and featured sections control

Communication

• Live chat between admin ↔ customer and admin ↔ deliveryman
• Order-specific customer support
• Push notification campaigns with target selection

Settings & Integrations

• Payment gateways: Stripe, PayPal, Razorpay, Flutterwave, and more
• SMS gateways: Twilio, Nexmo (Vonage)
• Email: SMTP, Gmail, AWS SES, Mailgun
• Firebase: Push notifications, social auth configuration
• Social login: Google, Facebook, Apple
• Google Maps: Geocoding, autocomplete, direction APIs
• Tax rates, currency configuration
• Delivery charge zones and rules
• Cookie consent configuration
• Environment variable management (in-app editor)

System & Security

• Built-in database backup & restore
• Application cache management
• Activity logs
• RBAC — fine-grained employee role permissions
• Two-Factor Authentication (TOTP) for admin accounts
• reCAPTCHA v3 on login
• JWT-based API authentication

Installer & Updater

• Built-in graphical installer wizard at /install
• Built-in updater at /updater — no SSH required for updates
• Purchase code verification

Prerequisites

First: Identify Your Hosting Type (VPS or Shared Hosting)

Commands and file paths in this documentation differ depending on whether your server is a VPS or shared hosting. Take 60 seconds to identify which one you have before installing — it determines which instructions and paths apply to you.

Throughout this documentation, path examples are labeled accordingly: paths beginning with /var/www/… are for a VPS, and paths beginning with /home/username/… are for shared hosting. Substitute your own username, domain, or folder name where they appear.

Server Requirements

Required PHP Extensions

The installer wizard automatically verifies all of these on the first step:

• PDO_MySQL — MySQL database driver
• Sodium — encryption and hashing
• Mbstring — multibyte string support
• OpenSSL — secure connections
• cURL — external HTTP requests
• Fileinfo — file type detection
• BCMath — arbitrary precision math
• XML — XML parsing
• Zip — archive handling
• GD or Imagick — image processing
• Swoole (optional) — required only for Laravel Octane

The installer also checks that Composer, Node.js, file_get_contents(), and symlink() are available.

External Services (Recommended)

• Firebase Project — push notifications, social auth, crashlytics
• Google Maps API Key — geocoding, place autocomplete, directions
• SMTP / Mail provider — transactional emails (Gmail, SES, Mailgun, etc.)
• AWS S3 bucket (optional) — file and image storage instead of local disk

Quick Start

Pre-flight Checklist

• PHP 8.2+ with all required extensions installed
• Composer 2.x installed globally
• Node.js 18+ and npm installed
• MySQL/MariaDB server running and accessible
• Empty database created for the application
• Web server (Nginx or Apache) configured
• Domain / subdomain pointed to the server
• Purchase code ready

5-Step Quick Install

1. Extract the archive Extract the downloaded ZIP to your server's web directory — VPS: e.g. /var/www/onemart (written as /path/to/your-project below); shared hosting: e.g. /home/username/your-project (see the cPanel walkthrough). Point your Nginx/Apache document root to the /public folder.
2. Set permissions

   # VPS (Ubuntu/Debian) — www-data is the web server user:
   chmod -R 775 storage bootstrap/cache
   chown -R www-data:www-data .
   
   # Shared hosting (cPanel) — skip chown (files already belong to your
   # cPanel user); only set the permissions:
   chmod -R 775 storage bootstrap/cache
   

3. Install dependencies & prepare environment The ZIP does not include the vendor/ folder — run composer update to generate it before continuing.

   composer update --optimize-autoloader --no-dev
   npm install
   npm run build
   cp .env.example .env
   php artisan key:generate
   php artisan jwt:secret
   

4. Run the installer wizard Visit https://yourdomain.com/install/requirements in your browser and follow the 5-step on-screen wizard (details below).
5. Post-install production optimization

   php artisan config:cache
   php artisan route:cache
   php artisan view:cache
   

Installation Process

Pre-Install: Create a MySQL Database

Create a MySQL database and user before running the installer wizard:

CREATE DATABASE onemart CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'onemart_user'@'localhost' IDENTIFIED BY 'strong_password_here';
GRANT ALL PRIVILEGES ON onemart.* TO 'onemart_user'@'localhost';
FLUSH PRIVILEGES;

Pre-Install: Environment & Dependencies

Copy the example environment file, generate keys, and install dependencies:

cp .env.example .env
php artisan key:generate
php artisan jwt:secret
composer update --optimize-autoloader --no-dev
npm install && npm run build

Web Installer Wizard

Navigate to https://yourdomain.com/install/requirements in your browser. The wizard guides you through 5 steps:

Step 1 — System Requirements Check

The installer verifies your server meets all requirements — PHP version, extensions, functions, and tool availability. All checks must show OK before you can proceed.

Step 2 — Purchase Verification

Enter your purchase code and username. Click Verify & Continue to validate your license. Upon success, the PURCHASE_VERIFIED=true flag is written to .env.

Step 3 — Database Configuration

Enter your MySQL connection details — Host, Port, Database name, Username, and Password. The installer tests the connection live before saving. On success, it writes the credentials to .env and automatically runs all database migrations.

Step 4 — Business & Admin Setup

Configure your business and create the super-admin account on this page:

• Business Setup: Business name, email, phone, and address
• Theme Setup: Primary color and secondary color (hex values, e.g. #6366F1)
• Administrator Account: First name, last name, email, password, and password confirmation (min 8 characters)

The installer creates the business record, the admin user, and runs essential seeders (currencies, website setup, general settings, push notification setup, email templates, modules).

Step 5 — Finalize Installation

Click Run to finalize the installation to complete the setup. The installer automatically:

• Generates the app key if not already set
• Clears all cached config, routes, and views
• Creates the public/storage symlink
• Sets INSTALLED=true, APP_ENV=production, APP_DEBUG=false
• Sets APP_URL to your current domain automatically

Installation Complete

Once finalized, the success screen appears with links to visit the Storefront or the Admin Panel. Your application is now live.

Post-Install Production Commands

# Cache for production performance
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Start queue worker (use Supervisor in production)
php artisan queue:work --sleep=3 --tries=3 --max-time=3600

# Optional: Start Octane for high performance
php artisan octane:start

Basic Configuration

Core .env Variables

Most of these are configured automatically by the installer wizard. Key values to review after installation:

# Application (set automatically by installer)
APP_NAME=DayOneMart
APP_ENV=production
APP_KEY=base64:YOUR_GENERATED_KEY
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Locale
APP_LOCALE=en
APP_FALLBACK_LOCALE=en

# Database (set by installer wizard — Step 3)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=onemart
DB_USERNAME=onemart_user
DB_PASSWORD=strong_password_here

# Session & Cache
SESSION_DRIVER=file
CACHE_STORE=file
QUEUE_CONNECTION=sync

FILESYSTEM_DISK=local

# Octane (optional — remove if not using Swoole)
OCTANE_SERVER=swoole

# JWT (generated via: php artisan jwt:secret)
JWT_SECRET=your_jwt_secret_here

# License (set automatically by installer)
INSTALLED=true
SOFTWARE_ID=20000000
PURCHASE_VERIFIED=true
PURCHASE_CODE=your_purchase_code
PURCHASE_USERNAME=your_username

Mail Configuration

Supported mail drivers and their key variables:

Storage Configuration

By default the application uses the local disk (storage/app/public). To switch to AWS S3, set FILESYSTEM_DISK=s3 and fill in the AWS_* variables in .env. No other code changes are needed.

Server Configuration

Nginx (Recommended)

server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name yourdomain.com www.yourdomain.com;

    # VPS path — e.g. /var/www/onemart/public
    root /path/to/your-project/public;
    index index.php;

    ssl_certificate     /etc/ssl/certs/yourdomain.crt;
    ssl_certificate_key /etc/ssl/private/yourdomain.key;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Content-Type-Options "nosniff";

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Apache (.htaccess)

The public/.htaccess file ships with the application. Ensure mod_rewrite is enabled:

a2enmod rewrite
systemctl restart apache2

SSL / HTTPS

Use Certbot (Let's Encrypt) for a free SSL certificate:

apt install certbot python3-certbot-nginx
certbot --nginx -d yourdomain.com -d www.yourdomain.com

Queue Worker (Supervisor)

Create a Supervisor config to keep the queue worker running persistently:

# /etc/supervisor/conf.d/onemart-worker.conf
# VPS only — Supervisor is not available on shared hosting
# (see the cPanel Limitations table below)

[program:onemart-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/your-project/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/onemart-worker.log
stopwaitsecs=3600

supervisorctl reread
supervisorctl update
supervisorctl start onemart-worker:*

Cron Job

VPS — add the Laravel scheduler to your crontab (crontab -e):

# VPS path — e.g. /var/www/onemart
* * * * * cd /path/to/your-project && php artisan schedule:run >> /dev/null 2>&1

Shared hosting — create the cron job via cPanel → Cron Jobs instead, using your home-directory path (php /home/username/your-project/artisan schedule:run) — see Step 9 of the cPanel walkthrough.

CORS Configuration

CORS headers are managed by Laravel's built-in CORS middleware (config/cors.php). If the Flutter apps or external services cannot reach the API, verify:

• allowed_origins includes your Flutter app's origin (or * for development)
• allowed_methods includes GET, POST, PUT, DELETE, OPTIONS
• allowed_headers includes Authorization, Content-Type, X-Requested-With, X-localization
• For production, restrict allowed_origins to your actual domains

Deployment

First-Time Deploy

The commands below assume a VPS shell session in the project root (e.g. cd /var/www/onemart). On shared hosting, follow the cPanel / Shared Hosting walkthrough below instead.

# 1. Install PHP dependencies
composer install --optimize-autoloader --no-dev

# 2. Build frontend assets
npm ci
npm run build

# 3. Run migrations and seeders
php artisan migrate --force
php artisan db:seed --force

# 4. Create storage symlink
php artisan storage:link

# 5. Cache everything for production
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

# 6. Set permissions
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data .    # VPS only — skip chown on shared hosting

Subsequent Deploys

# Pull latest code
git pull origin main

# Refresh dependencies
composer install --optimize-autoloader --no-dev
npm ci && npm run build

# Run new migrations
php artisan migrate --force

# Clear caches then rebuild
php artisan optimize:clear
php artisan optimize

# Restart Octane / queue workers
php artisan octane:reload   # if using Octane
supervisorctl restart onemart-worker:*

Post-Deploy Checklist

• Visit the storefront homepage and confirm products render
• Log in to the admin panel and verify the dashboard loads
• Place a test order end-to-end
• Check queue worker is processing jobs (php artisan queue:monitor)
• Verify email notifications are delivered
• Test push notifications are delivered (Firebase)
• Confirm file uploads and storage links work

cPanel / Shared Hosting

Step 1 — Create a Database

• Open cPanel → MySQL Database Wizard
• Create a new database (e.g. youruser_onemart)
• Create a database user and set a strong password
• Assign ALL PRIVILEGES to the user on that database

Step 2 — Upload & Extract Files

• Open cPanel → File Manager
• Upload install.zip to /home/username/ (above public_html)
• Extract the archive — this creates a project folder (e.g. /home/username/your-project/)

Step 3 — Set the Document Root

Laravel requires the domain to point to the /public folder. On cPanel you have two options:

Option A — Subdomain / Addon Domain (Recommended)

• Go to cPanel → Domains (or Subdomains / Addon Domains)
• Set the document root to /home/username/your-project/public
• This is the cleanest approach — no file moving required

Option B — Move Public Files (if document root cannot be changed)

• Move all contents from /onemart/public/ into /public_html/
• Edit public_html/index.php and update the paths:

// Change these two lines:
require __DIR__.'/../vendor/autoload.php';
$app = require_once __DIR__.'/../bootstrap/app.php';

// To point to the project folder:
require __DIR__.'/../onemart/vendor/autoload.php';
$app = require_once __DIR__.'/../onemart/bootstrap/app.php';

Step 4 — Set Permissions

Via cPanel → Terminal (SSH) or File Manager:

cd /home/username/your-project
chmod -R 775 storage bootstrap/cache
chmod 644 .env

Step 5 — Install Dependencies

The install package does not include the vendor/ folder, so you must generate it with composer update. Connect via SSH and run:

cd /home/username/your-project
composer update --optimize-autoloader --no-dev
cp .env.example .env
php artisan key:generate
php artisan jwt:secret

Step 6 — Build Frontend Assets

If your hosting provides Node.js via SSH:

npm install
npm run build

Step 7 — Run the Installer Wizard

• Visit https://yourdomain.com/install/requirements in your browser
• Follow the 5-step wizard: requirements check → purchase verification → database setup → business & admin setup → finalize

Step 8 — Create the Storage Symlink

php artisan storage:link

Step 9 — Set Up the Cron Job

• Open cPanel → Cron Jobs
• Set the interval to Once Per Minute (* * * * *)
• Enter the command:

php /home/username/your-project/artisan schedule:run >> /dev/null 2>&1

Step 10 — Production Optimization

php artisan config:cache
php artisan route:cache
php artisan view:cache

cPanel Limitations

Update Procedure

Using the Built-in Updater (Recommended)

1. Back up your database Go to Admin Panel → Settings → System → Database Backup and download a fresh backup.
2. Navigate to the updater Visit https://yourdomain.com/updater while logged in as admin.
3. Upload the update ZIP file Download the latest update package and upload it via the updater. The file is uploaded in chunks for reliability on large updates.
4. Run the update Click the update button. The updater extracts files, runs migrations, and clears caches automatically. You will be redirected to a success page upon completion.
5. Regenerate the vendor/ folder Connect via SSH and run composer update in the project root to install the new PHP dependencies that ship with the update:

   # VPS:            cd /path/to/your-project   (e.g. /var/www/onemart)
   # Shared hosting: cd /home/username/your-project
   cd /path/to/your-project
   composer update --optimize-autoloader --no-dev
   php artisan optimize:clear
   php artisan optimize
   

   On shared hosting without SSH/Composer, run composer update locally and upload the regenerated vendor/ folder via File Manager or FTP.

Manual Update via SSH

The update ZIP does not contain the vendor/ folder — Step 4 below regenerates it with composer update. Skipping that step will leave the site broken.

# 1. Put application in maintenance mode
php artisan down --message="Updating, back in 5 minutes" --retry=300

# 2. Backup database
#    (VPS shown; on shared hosting use your cPanel DB user, e.g. youruser_onemart)
mysqldump -u root -p onemart > backup_$(date +%Y%m%d).sql

# 3. Extract and overwrite files (keep your .env and storage/)
# Do NOT overwrite .env or storage/

# 4. Regenerate vendor/ and rebuild frontend assets
#    (the update package does not ship with vendor/)
composer update --optimize-autoloader --no-dev
npm ci && npm run build

# 5. Run migrations
php artisan migrate --force

# 6. Rebuild cache
php artisan optimize:clear && php artisan optimize

# 7. Bring application back online
php artisan up

Localization

The application supports 5 languages out of the box with full RTL support for Arabic:

Adding a New Language

1. Backend: Copy the lang/en/ folder to lang/{code}/ and translate all PHP files.
2. Admin frontend: Copy resources/js/AdminPanel/locales/en.json to {code}.json and translate.
3. Storefront: Copy resources/js/StoreFront/locales/en.json to {code}.json and translate.
4. Sort locale files: Run npm run sort:locales to ensure consistent key ordering across all files.

Branding & Customization

This section is for store owners — no coding required. Everything below is done from the Admin Panel → Settings after installation, so you can make the platform your own: your business name, logo, favicon, and brand colors. A developer-level theming guide (for deeper visual changes) follows at the end. For the complete solution-wide walkthrough — including renaming both mobile apps, app icons, splash screens, and content customization — see the dedicated Branding & Customization Guide.

1 2 3 4

Fields on this screen

1. Business Name — displayed across the storefront header, emails, and browser tab title (alongside email, phone, country, time zone, and address).
2. Logo — your main brand logo shown in the storefront and admin header (JPG/PNG/JPEG, max 2 MB, ~120 × 80 px).
3. Icon — the favicon shown in the browser tab (JPG/PNG/JPEG, max 2 MB).
4. Admin Primary & Secondary Color — the accent colors (hex) used for buttons, links, and highlights.

1. Business Name & Identity

1. Open Business Setup Go to Admin Panel → Settings → Business Setup → Basic Info.
2. Set your business name, email, phone, and address These appear in the storefront header/footer, on invoices, and in transactional emails.
3. Save Changes take effect immediately on the storefront — no rebuild or redeploy required.

2. Logo & Favicon

Upload your brand images from Admin Panel → Settings → Business Setup:

3. Primary Color Scheme

The brand colors set the accent used for buttons, links, badges, and highlights across the storefront and mobile apps.

1. Set the colors during install The installer's Step 4 — Theme Setup asks for a primary and secondary color as hex values (for example #6366F1).
2. Change them any time later Update the primary/secondary colors from Admin Panel → Settings → Business Setup. The storefront picks up the new colors on the next page load.
3. Match your mobile apps To keep branding consistent, set the same hex values in each Flutter app's theme file — see App Theme & Colors in the Customer App and Deliveryman App docs.

4. Developer Theming (Advanced)

For deeper visual changes beyond the admin settings, the storefront and admin UI are styled with Tailwind CSS driven by CSS variables:

• Edit the color tokens and design variables in resources/css/app.css.
• Admin panel pages live in resources/js/AdminPanel/Pages/; storefront pages in resources/js/StoreFront/Pages/.
• Shared UI components are in resources/js/components/.
• After any code-level change, rebuild assets with npm run build.

API Reference (Developers)

The application ships with a Postman collection (postman-collection.json, ~485 KB) covering all API endpoints. Import it into Postman or Insomnia for interactive exploration.

Base URL & Versioning

Base URL:  https://yourdomain.com/api/v1
Auth:      Bearer JWT token (Authorization: Bearer {token})

Authentication Flow (JWT)

The API uses JWT bearer tokens (tymon/jwt-auth). A client logs in once, stores the returned token, and sends it on every subsequent request.

1. Log in to obtain a token

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "customer@example.com",
  "password": "secret123"
}

Response

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user": { "id": 12, "name": "Jane Doe", "email": "customer@example.com" }
  }
}

2. Call a protected endpoint with the token

GET /api/v1/customer/orders
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

3. Refresh an expiring token

POST /api/v1/auth/refresh
Authorization: Bearer {current_token}

Standard Request Headers

Standard Response Envelope

All API responses follow a consistent JSON shape, so clients can parse them uniformly:

// Success
{ "success": true,  "message": "...", "data": { ... } }

// Paginated list
{ "success": true, "data": [ ... ], "meta": { "current_page": 1, "last_page": 5, "total": 92 } }

// Validation / error
{ "success": false, "message": "The given data was invalid.",
  "errors": { "email": ["The email field is required."] } }

HTTP Status & Error Codes

Customer API Endpoints

Admin API Endpoints

Deliveryman API Endpoints

Troubleshooting

Common Environment Configuration Errors (.env)

Most post-install failures trace back to one of these .env misconfigurations. After any .env change, run php artisan config:clear (and php artisan config:cache in production) or the change will not take effect.

500 — Internal Server Error

• Check storage/logs/laravel.log for the root cause
• Set APP_DEBUG=true temporarily in .env to see the exception in the browser
• Run php artisan config:clear && php artisan cache:clear
• Verify storage/ and bootstrap/cache/ are writable by the web server

Vite Manifest Not Found

npm install
npm run build
php artisan view:clear

Images / Uploads Not Showing

php artisan storage:link
# If the symlink already exists but is broken:
rm public/storage
php artisan storage:link

404 — Page Not Found

• Confirm the document root points to /public — on a VPS check your Nginx/Apache config; on shared hosting check cPanel → Domains → Document Root
• For Nginx: ensure try_files $uri $uri/ /index.php?$query_string; is present
• For Apache: confirm mod_rewrite is enabled and AllowOverride All is set

Emails Not Sending

• Verify MAIL_* variables in .env are correct
• Ensure the queue worker is running (php artisan queue:work)
• Check storage/logs/laravel.log for mail errors
• Test with php artisan tinker: Mail::raw('test', fn($m) => $m->to('test@example.com'));

CSRF Token Mismatch

• Clear browser cookies and try again
• Verify APP_URL in .env matches the actual domain (including https://)
• Run php artisan config:clear

Queue Jobs Not Processing

# Check if queue worker is running
supervisorctl status onemart-worker:*

# Restart if needed
supervisorctl restart onemart-worker:*

# Run manually to debug
php artisan queue:work --verbose

Push Notifications Not Working

• Verify Firebase credentials are configured correctly in Admin Panel → Settings → Firebase
• Ensure the Firebase service account JSON file is uploaded and valid
• Check that the FCM server key matches your Firebase project
• Confirm the device has granted notification permissions
• Check storage/logs/laravel.log for FCM errors

Permission Errors

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

FAQ & Environment-Specific Issues

Answers to the most common questions and environment-specific hurdles encountered during installation and deployment across different hosting setups (VPS, shared hosting, cloud, and local development).

Database connection timeouts

Symptoms: SQLSTATE[HY000] [2002] Connection timed out, [2002] Connection refused, or [2006] MySQL server has gone away during the installer's database step or while the app is running.

• Confirm DB_HOST is correct. On many managed/cloud databases the host is a remote endpoint, not 127.0.0.1. Using localhost forces a socket connection — use 127.0.0.1 to force TCP if the socket path differs.
• Verify the database server is reachable from the web server: telnet DB_HOST 3306 or nc -zv DB_HOST 3306.
• Open port 3306 in the firewall / security group, and whitelist the web server's IP in your cloud database's access list.
• For large seeders/imports timing out, raise MySQL wait_timeout and max_allowed_packet, and PHP max_execution_time (see below).
• Double-check the credentials and database name match exactly what you created in Installation Process → Pre-Install: Create a MySQL Database.

Permission errors (storage / bootstrap / cache)

Symptoms: The stream or file "storage/logs/laravel.log" could not be opened: failed to open stream: Permission denied, or a white screen after install.

# Grant read/write to the framework-managed directories
chmod -R 775 storage bootstrap/cache

# Give ownership to the web-server user
#   Nginx/Apache on Ubuntu/Debian: www-data
#   Apache on CentOS/RHEL:          apache
#   cPanel/shared hosting:          your cPanel username
chown -R www-data:www-data storage bootstrap/cache

• Use the correct web-server user for your OS (see the comments above).
• On SELinux systems (CentOS/RHEL), also allow httpd write access: chcon -R -t httpd_sys_rw_content_t storage bootstrap/cache.
• On shared hosting, set folders to 755 and files to 644 if 775 is rejected by the host's security policy.

"No application encryption key has been specified"

php artisan key:generate
php artisan config:clear

Installer times out or fails midway (max_execution_time / memory_limit)

Migrations and seeders can exceed conservative PHP limits on shared hosting. Raise these in php.ini (or via .user.ini / cPanel → MultiPHP INI Editor):

max_execution_time = 300
memory_limit = 512M
max_input_time = 300

Large update ZIP or CSV import is rejected

Increase the upload limits so the updater and bulk import can accept larger files:

upload_max_filesize = 128M
post_max_size = 128M

419 — Page Expired on login

• Ensure APP_URL exactly matches the address in the browser, including https:// and any subdomain.
• Confirm storage/framework/sessions is writable (see permission errors above).
• Clear browser cookies for the domain, then run php artisan config:clear.

Assets load over HTTP / mixed-content warnings behind a proxy or load balancer

• Set APP_URL=https://yourdomain.com in .env.
• Behind a reverse proxy/load balancer terminating SSL, ensure the X-Forwarded-Proto header is forwarded so Laravel generates https URLs.
• Run php artisan config:cache after changing APP_URL.

Composer runs out of memory on shared hosting

php -d memory_limit=-1 $(which composer) update --optimize-autoloader --no-dev

If Composer or SSH is unavailable, run composer update locally and upload the generated vendor/ folder — the package ships without it by design.

Emails, push notifications, or payments are not working after install

These integrations are configured in Admin Panel → Settings after installation, not in .env. See the Troubleshooting section for driver-specific checks.

Extending the Platform

This section is for developers building on top of DayOneMart. The codebase follows standard Laravel 12 conventions with a service-oriented structure, so most extensions are additive — you add controllers, services, routes, and Vue pages without modifying core files.

Architecture at a Glance

Add a New API Endpoint (End-to-End)

1. Create a controller Place it under app/Http/Controllers/Api/ and keep it thin — delegate logic to a service.

   php artisan make:controller Api/V1/Customer/FavoriteController
   

2. Add a Form Request for validation

   php artisan make:request StoreFavoriteRequest
   

3. Put the business logic in a service Add a class under app/Services/ and inject it into the controller's constructor.
4. Return an API Resource Transform the model with a Resource in app/Http/Resources/ so the response matches the standard envelope (success, message, data).
5. Register the route Add it to the correct file — routes/api/v1/customer.php, admin.php, or deliveryman.php — inside the JWT auth:api middleware group.

   Route::middleware('auth:api')->group(function () {
       Route::apiResource('favorites', FavoriteController::class);
   });
   

6. Test it Call the new route with a bearer token, then add it to postman-collection.json so it stays documented.

Events & Listeners

Decouple side-effects (emails, push notifications, logs) from your core flow by firing events instead of calling services inline:

# Generate an event and a listener
php artisan make:event OrderPlaced
php artisan make:listener SendOrderPushNotification --event=OrderPlaced

# Dispatch from anywhere in your code
event(new OrderPlaced($order));

Register the mapping in app/Providers/EventServiceProvider.php (or via auto-discovery).

Queued Jobs (Background Work)

Offload slow work (bulk notifications, exports, third-party API calls) to the queue so requests stay fast:

php artisan make:job ProcessBulkImport

# Dispatch it
ProcessBulkImport::dispatch($payload);

Add a Database Column / Migration

php artisan make:migration add_gift_note_to_orders_table
# edit the migration, then:
php artisan migrate

Add an Admin Page / Module

1. Create the Vue page under resources/js/AdminPanel/Pages/, following an existing module (e.g. Orders/) as a template.
2. Add a web route in routes/web/admin.php that renders the page via Inertia.
3. Add the sidebar/menu entry and wire up any RBAC permission so it respects employee roles.
4. Rebuild assets with npm run build (or npm run dev during development).

Backend — Controllers & Services (Reference)

• API controllers live in app/Http/Controllers/Api/
• Business logic is extracted to app/Services/
• Eloquent models are in app/Models/
• Follow standard Laravel conventions — register new routes in routes/api/v1/

Frontend — Vue & Tailwind

• Admin panel pages: resources/js/AdminPanel/Pages/
• Storefront pages: resources/js/StoreFront/Pages/
• Shared components: resources/js/components/
• Add Shadcn components: npm run shadcn:admin or npm run shadcn:storefront
• Tailwind config is driven by CSS variables — edit resources/css/app.css to change the color scheme
• After changes, rebuild with npm run build

Translations / i18n

• Backend translations: lang/{en,bn,hi,ar,es}/
• Admin frontend locales: resources/js/AdminPanel/locales/
• Storefront locales: resources/js/StoreFront/locales/
• Sort locale files after editing: npm run sort:locales

Adding a Payment Gateway

1. Create the controller in app/Http/Controllers/Payment/ implementing the gateway's webhook and redirect callbacks.
2. Register routes in routes/payment.php.
3. Add the gateway to settings — register it in the admin panel's payment gateway list and add the necessary .env variables.

Email Templates

Laravel Mailable classes are in app/Mail/. Blade email views are in resources/views/emails/. Customize the HTML/CSS directly in those files.

Development Workflow

# Start all dev services concurrently (PHP server + queue listener + logs + Vite)
composer dev

# Or start individually:
php artisan serve                    # PHP dev server on port 8000
npm run dev                          # Vite dev server with HMR
php artisan queue:listen --tries=1   # Queue listener
php artisan pail                     # Tail logs in terminal

# Optional services:
php artisan octane:start             # Octane performance server (if enabled)

Need help? Reach us via the item’s Support tab on CodeCanyon or dayonesoft.com or visit our website for support.