Vozex Marketplace and POS Product Setup Guide

1. System Overview

The vozex repository is the central marketplace and fulfillment control plane. It manages public product pages, customer checkout, orders, licenses, subscriptions, hosted installations, payment gateway integration, and admin operations.

The point-of-sale repository is a separate product repository. In this setup it acts as a multi-tenant SaaS product that Vozex sells and provisions. Vozex stores the product catalog record, pricing mappings, Dodo / PayPal identifiers, and fulfillment configuration. POS exposes machine-to-machine marketplace endpoints for onboarding, status, suspend, and cancel actions.

2. Prerequisites

• PHP 8.2+ for vozex/backend
• PHP 8.1+ for point-of-sale/backend
• Composer
• Node.js 20+ and npm
• MySQL if not using SQLite locally
• Redis recommended for queues / cache in larger local setups
• Git
• A valid Dodo test or live API key set
• Optional PayPal sandbox or live credentials if PayPal is enabled

3. Vozex Setup

3.1 Backend install

cd C:\projects\vozex\backend
copy .env.example .env
composer install
php artisan key:generate
php artisan migrate
php artisan db:seed
npm install
npm run build

3.2 Backend dev run

cd C:\projects\vozex\backend
composer run dev

The backend composer.json already defines a combined dev runner that starts:

• php artisan serve
• php artisan queue:listen
• php artisan pail
• npm run dev

3.3 Frontend install

cd C:\projects\vozex\frontend
copy .env.example .env
npm install
npm run dev

3.4 Minimum local env values

APP_URL=http://localhost:8000
APP_FRONTEND_URL=http://localhost:5173
FRONTEND_URL=http://localhost:5173

DB_CONNECTION=sqlite
QUEUE_CONNECTION=database
CACHE_STORE=database
SESSION_DRIVER=database

DODO_ENVIRONMENT=sandbox
DODO_TEST_API_KEY=your_test_key
DODO_TEST_SECRET_KEY=your_test_secret
DODO_TEST_WEBHOOK_SECRET=your_test_webhook_secret

PAYPAL_MODE=sandbox
PAYPAL_CLIENT_ID=
PAYPAL_CLIENT_SECRET=
PAYPAL_WEBHOOK_ID=

3.5 Seeders relevant to the POS product

• backend/database/seeders/MarketplaceSeeder.php creates the marketplace product record and pricing
• backend/database/seeders/DatabaseSeeder.php runs global app seed logic
• backend/database/seeders/CompanyPagesSeeder.php seeds company / informational pages

3.6 Main public and admin APIs

• Public products: GET /api/products, GET /api/products/{slug}
• Checkout: POST /api/checkout/calculate, POST /api/checkout/create
• Dodo admin: POST /api/admin/dodo/products/create, PUT /api/admin/dodo/products/{id}/sync
• Pricing mappings: GET /api/admin/products/{productId}/pricing-mappings, POST /api/admin/products/pricing-mappings/bulk
• Webhooks: POST /api/webhooks/dodo, POST /api/webhooks/paypal

4. POS Setup

4.1 Backend install

cd C:\projects\point-of-sale\backend
copy .env.example .env
composer install
php artisan key:generate
php artisan migrate
php artisan db:seed

4.2 Frontend install

cd C:\projects\point-of-sale\frontend
npm install
npm run dev

4.3 POS product stack

• Laravel 10 backend with JWT auth and Stancl tenancy
• React 19 frontend with React Query
• Optional Electron packaging for desktop POS builds
• Tenant API routes live under backend/routes/tenant_api.php

4.4 POS module coverage

• POS billing, held orders, split payments, invoices, returns, refunds
• Inventory, stock adjustments, warehouse transfers, stock counts, reorder suggestions
• Suppliers, purchase orders, GRN, supplier returns, supplier invoices
• Customers, credit, loyalty, promotions, SMS, statements
• Electronics flows: quotations, service jobs, serials, warranties, trade-ins
• Accounting, expenses, closings, reports
• HRM, attendance, leave, overtime, payroll
• Central admin: tenants, subscriptions, branding, backup, support, monitoring

4.5 Existing product documentation in the POS repo

• C:\projects\point-of-sale\CUSTOMER_GUIDE.html
• C:\projects\point-of-sale\VOZEX_MARKETPLACE_COMPATIBILITY_AUDIT.md
• C:\projects\point-of-sale\POS_HEADLESS_CONTROL_PLANE_ADOPTION_PLAN.md

5. Vozex to POS Integration

5.1 What Vozex expects from POS

The POS repository must expose a central machine-to-machine API so Vozex can provision and control tenants.

POST /api/marketplace/onboard
POST /api/marketplace/status
POST /api/marketplace/suspend
POST /api/marketplace/cancel

5.2 Required auth model

Authorization: Bearer <MARKETPLACE_SHARED_TOKEN>

5.3 Vozex product fulfillment config for POS

{
  "base_url": "https://pos.vozex.cloud",
  "onboard_endpoint": "/api/marketplace/onboard",
  "status_endpoint": "/api/marketplace/status",
  "suspend_endpoint": "/api/marketplace/suspend",
  "cancel_endpoint": "/api/marketplace/cancel",
  "auth_mode": "bearer",
  "credentials_ref": "pos_marketplace_token",
  "timeout_seconds": 45,
  "management": {
    "enabled": true,
    "base_url": "https://pos.vozex.cloud",
    "overview_endpoint": "/api/marketplace/admin/overview",
    "tenants_endpoint": "/api/marketplace/admin/tenants",
    "tenant_details_endpoint": "/api/marketplace/admin/tenants/{tenant}",
    "tenant_status_endpoint": "/api/marketplace/admin/tenants/{tenant}/status",
    "tenant_subscription_endpoint": "/api/marketplace/admin/tenants/{tenant}/subscription",
    "plans_endpoint": "/api/marketplace/admin/plans"
  }
}

5.4 Product record fields used by Vozex for POS

5.5 Seeded POS marketplace product

The seeded marketplace record is currently created from backend/database/seeders/MarketplaceSeeder.php as Point of Sale SaaS Suite. That seeder also configures pricing mappings, tags, SEO fields, and fulfillment metadata.

6. Payments and Pricing

6.1 Dodo payment configuration

Vozex uses App\Services\DodoPaymentService and admin product tooling in AdminProducts.jsx. Product records can store variant-specific Dodo IDs:

• dodo_product_id_regular
• dodo_product_id_extended
• dodo_product_id_monthly
• dodo_product_id_yearly

6.2 Pricing mappings

Product variant pricing should be managed through product_pricing_mappings instead of relying only on base fields. The current sync logic resolves pricing mappings first and falls back only if no mapping price exists.

6.3 Duplicate prevention now implemented

• Existing Dodo products are re-used through lookup before creating new ones
• Environment mismatch handling recreates and re-links missing live or test IDs safely
• Pricing modal passes stable metadata so the same mapping is not re-created repeatedly
• Admin buttons for setup, sync, and save are disabled while a request is in progress

6.4 PayPal support

PayPal config is handled by App\Services\Payments\Gateways\PayPalPaymentGateway and admin settings endpoints under /api/admin/paypal/*. Use sandbox IDs in local setups first.

7. Operational Flows

7.1 Marketplace order to POS tenant flow

1. User browses products from Vozex frontend marketplace pages.
2. User selects a POS pricing variant and checks out.
3. Payment is created through Dodo or PayPal.
4. Webhook confirms the payment in Vozex.
5. Vozex creates fulfillment records and routes the order to the multitenant SaaS adapter.
6. Vozex calls the POS onboarding endpoint with the tenant payload.
7. POS provisions tenant resources and returns workspace details.
8. Vozex stores installation / subscription state and exposes it in the customer dashboard.

7.2 Local testing sequence

1. Seed marketplace products
2. Verify POS product exists in admin products
3. Create or sync Dodo products
4. Confirm pricing mappings are saved
5. Hit checkout calculate
6. Create checkout session
7. Simulate or receive payment webhook
8. Retry or inspect fulfillments if needed

8. Vozex Folder Map

8.1 Repository root

C:\projects\vozex
|-- backend
|-- frontend
|-- DETAILED_MULTI_PRODUCT_FLOW.md
|-- MULTITENANT_MARKETPLACE_AUTOMATION_PLAN.md
|-- MULTI_PRODUCT_PURCHASE_FLOW.md
|-- VOZEX_CENTRAL_SAAS_CONTROL_PLANE_PLAN.md
`-- VOZEX_UNIVERSAL_FULFILLMENT_IMPLEMENTATION_AUDIT.md

8.2 Backend app map

C:\projects\vozex\backend\app
+---Console\Commands
+---Http\Controllers\Api
+---Http\Middleware
+---Http\Requests
+---Jobs
+---Models
+---Notifications
+---Providers
+---Services
|   +---Fulfillment\Adapters
|   +---Payments\Gateways
|   `---Products
`---Support

8.3 Frontend src map

C:\projects\vozex\frontend\src
|-- admin
|-- assets
|-- components
|-- context
|-- data
|-- hooks
|-- pages
|-- services
`-- utils

8.4 Backend directory purpose

9. POS Folder Map

9.1 Repository root

C:\projects\point-of-sale
|-- backend
|-- customer-guide-site
|-- deploy
|-- docker
|-- frontend
|-- CUSTOMER_GUIDE.html
|-- POS_HEADLESS_CONTROL_PLANE_ADOPTION_PLAN.md
|-- STANCL_TENANCY_FULL_IMPLEMENTATION_FLOW.md
`-- VOZEX_MARKETPLACE_COMPATIBILITY_AUDIT.md

9.2 Backend app map

C:\projects\point-of-sale\backend\app
|-- Console\Commands
|-- Http\Controllers\Admin
|-- Http\Controllers\Api
|-- Http\Middleware
|-- Models
|-- Providers
|-- Services
|   `-- Tenancy
`-- Traits

9.3 Frontend src map

C:\projects\point-of-sale\frontend\src
|-- assets
|-- components
|   |-- accounting
|   |-- hrm
|   `-- reports
|-- context
|-- hooks
|-- i18n
|-- pages
|   `-- admin
|-- services
`-- utils

9.4 POS key areas for Vozex integration

10. Key File Guide

11. Deployment Checklist

11.1 Vozex

• Set production APP_URL and FRONTEND_URL
• Configure database, mail, queue, cache, and storage
• Set Dodo live keys and DODO_ENVIRONMENT=live
• Set PayPal live credentials if PayPal is enabled
• Run php artisan migrate --force
• Run php artisan db:seed --class=MarketplaceSeeder if product data must exist
• Ensure queue worker and scheduler are running
• Publish or build frontend assets

11.2 POS

• Expose central API domain reachable from Vozex backend
• Configure shared marketplace token in the POS env
• Ensure tenant DB provisioning permissions exist
• Run migrations and seeders
• Run scheduler for lifecycle and background operations
• Confirm marketplace routes respond correctly before enabling live sales

* * * * * php /path/to/vozex/backend/artisan schedule:run
* * * * * php /path/to/point-of-sale/backend/artisan schedule:run

12. Troubleshooting

Dodo product sync returns 404

Cause: stored Dodo product IDs belong to the wrong environment. The current sync path now recreates or re-links IDs when live or test IDs do not exist in the active environment.

Pricing sync uses the wrong price

Cause: mapping was not saved or no active mapping matched the variant. Current sync logic resolves pricing mappings first, then falls back to product base fields.

Pricing mapping save creates duplicate Dodo products

Cause: repeated save or missing lookup metadata. Current create-single logic now performs a Dodo lookup before create and the UI disables the save button while the request is running.

POS onboarding does not run after payment

Check the product delivery_model, fulfillment_driver, fulfillment_config, webhook processing, and fulfillment retry logs in Vozex.

Useful verification commands

cd C:\projects\vozex\backend
php artisan route:list
php artisan migrate:status
php artisan queue:work

cd C:\projects\point-of-sale\backend
php artisan route:list --path=marketplace --except-vendor
php artisan schedule:list