# VOZEX Central SaaS Control Plane Plan

## Objective
Turn `Vozex` into a true multi-product SaaS control plane.

After this architecture:
- every SaaS product is sold from Vozex
- fulfillment still happens product-wise
- tenant/subscription lifecycle is managed from Vozex
- product-specific admin panels become optional operational backdoors, not daily-use consoles
- each product exposes a headless management API that Vozex consumes

## Target Architecture
1. `Vozex` owns:
- product catalog
- checkout and billing
- customer identity
- order to fulfillment orchestration
- product capability registry
- tenant lifecycle control per product
- subscription lifecycle control per product
- product health and operational dashboards

2. SaaS products own:
- domain-specific business logic
- tenant database and runtime
- headless management API for Vozex
- provisioning and low-level operations

3. Contract model:
- product record in Vozex stores `fulfillment_config`
- `fulfillment_config.management` defines headless admin API endpoints
- Vozex uses one central `Product Operations` console to manage all SaaS products

## Product Capability Model
Each SaaS product must declare:
- `delivery_model = saas_multitenant`
- `fulfillment_driver = multitenant_saas`
- `external_provider`
- `external_product_ref`
- `fulfillment_config.base_url`
- `fulfillment_config.onboard/status/suspend/cancel`
- `fulfillment_config.management.enabled`
- `fulfillment_config.management.overview_endpoint`
- `fulfillment_config.management.tenants_endpoint`
- `fulfillment_config.management.tenant_details_endpoint`
- `fulfillment_config.management.tenant_status_endpoint`
- `fulfillment_config.management.tenant_subscription_endpoint`
- `fulfillment_config.management.plans_endpoint`

## Vozex Files Updated / Required
### Implemented now
- `backend/app/Http/Controllers/Api/ProductController.php`
- `backend/app/Http/Requests/StoreProductFulfillmentRequest.php`
- `backend/app/Http/Requests/UpdateProductFulfillmentRequest.php`
- `backend/app/Services/Fulfillment/FulfillmentConfigValidator.php`
- `backend/app/Services/Products/ExternalProductManagementService.php`
- `backend/app/Http/Controllers/Api/AdminProductOperationsController.php`
- `backend/routes/api.php`
- `backend/database/seeders/MarketplaceSeeder.php`
- `backend/tests/Feature/AdminProductSaveFlowTest.php`
- `backend/tests/Feature/AdminProductOperationsTest.php`
- `frontend/src/admin/AdminProducts.jsx`
- `frontend/src/admin/AdminProductOperations.jsx`
- `frontend/src/admin/Dashboard.jsx`

### Next expansion stages
- product health polling job per provider
- unified action logs per external product
- provider rate limit protection and retries
- product capability presets/templates
- granular product-ops permissions

## Central Management Flow
1. Admin creates SaaS product in Vozex.
2. Product config stores fulfillment + management endpoints.
3. Customer buys product from Vozex.
4. Vozex payment/webhook marks order paid.
5. Vozex `MultiTenantSaasAdapter` calls product onboarding API.
6. Product provisions tenant and returns workspace details.
7. Vozex stores fulfillment record and external tenant link.
8. Admin later uses `Product Operations` page in Vozex.
9. Vozex calls product management API to:
- list tenants
- view tenant health/summary
- activate/suspend/cancel tenant
- change subscription plan/status

## Governance Rules
- product UI must not be required for daily tenant lifecycle work
- every SaaS product must expose the same control-plane contract
- secrets should be referenced through `credentials_ref` or environment-backed values
- product-specific custom logic is allowed only behind the shared contract

## Checklist
- [x] add central management config to SaaS product schema
- [x] auto-default management endpoints for multitenant SaaS products
- [x] validate management endpoints in product save flow
- [x] add Vozex remote management service
- [x] add Vozex admin product operations API
- [x] add Vozex admin product operations UI
- [x] seed POS product with central management endpoints
- [ ] add per-product health sync job
- [ ] add centralized operational audit trail for remote actions
- [ ] add product capability presets for new SaaS products
- [ ] add multi-provider dashboards on overview screen

## Rollout Order For New SaaS Products
1. Build product headless management API.
2. Register product in Vozex with SaaS multitenant config.
3. Test onboarding from Vozex checkout.
4. Test product operations actions from Vozex admin.
5. Disable dependence on the product's standalone admin panel for routine support.