# MASTER PROMPT — White Label Multi-Tenant Business Management Platform

**(ERP + POS + CRM + Service Management + E-commerce)**

**Project name:** KarobariSuite

## Primary Delivery Focus (Read First)

**For the first complete delivery of this project, focus ONLY on:**

1. **APIs** — versioned REST JSON APIs (`/api/v1`), JWT auth, OpenAPI/Swagger  
2. **Web App** — PHP Templates + HTML5 + CSS3 + Vanilla JS portals in the browser  

| Build now | Defer |
| --- | --- |
| Platform Admin (Web) | Native iOS / Android apps |
| Vendor Admin (Web) | White-label mobile apps |
| POS as **Web App** (browser) | Offline-native mobile POS |
| Customer Portal (Web) | Flutter / React Native clients |
| Vendor Website (Web) | Marketplace mobile experience |
| Public + private REST APIs | Desktop installers |

### Parallel delivery model

Work **APIs and Web App simultaneously** so the project can be completed as one shippable product:

| Track A — API | Track B — Web App |
| --- | --- |
| Auth, tenants, RBAC | Login / session UX against same APIs |
| Module endpoints (products, inventory, POS, orders…) | Admin / POS / portal screens calling those APIs |
| OpenAPI contracts | Forms, tables, dashboards consuming contracts |
| PHPUnit API tests | Web UI flows + integration against APIs |

**Rule:** The Web App must consume the same public APIs (no hidden “web-only” business logic bypass). Shared domain services may be used server-side, but contracts stay API-first.

**Do not** design or implement mobile apps, marketplace apps, or native clients until APIs + Web App MVP is complete and stable.

---

## Project Scope

### Purpose

KarobariSuite exists to give small and medium businesses **one branded digital operating system** for running their company — sales, inventory, customers, services, staff, accounting, marketing, and online storefront — without buying and stitching together many separate tools.

The platform owner runs KarobariSuite as a **multi-tenant SaaS**. Each vendor (tenant) gets an isolated, white-labeled workspace that looks and feels like **their own product**, not a shared generic app.

### Why this project exists

Most SMBs today struggle with:

- Spreadsheets or disconnected apps for stock, billing, and customers
- Expensive, complex ERPs that are hard to adopt
- Separate POS, website, booking, and CRM tools that do not sync
- No affordable white-label option (their customers see a third-party brand)
- Industry needs that differ (retail vs salon vs clinic) but budgets that do not allow custom software

KarobariSuite solves this by offering a **modular, configurable, white-label business suite** that vendors subscribe to and brand as their own.

### What the project is (in one sentence)

A **white-label, multi-tenant Business Management Platform** (ERP + POS + CRM + Services + E-commerce) built so platform owners can sell subscriptions to vendors, and vendors can digitally run and grow their business under their own brand.

### What the project is not

- Not a single-shop inventory script
- Not a marketplace-only app (marketplace is a later evolution)
- Not a one-industry product (architecture must support many industries via modules)
- Not a microservices rewrite exercise — start as a **modular Pure PHP monolith**
- **Not a mobile-first build for v1** — v1 is **APIs + Web App only**

### Target users

| Audience | Who they are | What they need |
| --- | --- | --- |
| **Platform Super Admin** | KarobariSuite operator / SaaS owner | Manage tenants, plans, billing, themes, health, support |
| **Vendor Owner** | Business owner (shop, salon, clinic, etc.) | Run operations, brand their portal, grow sales |
| **Vendor Staff** | Employees with roles | Do assigned work (POS, inventory, appointments, etc.) |
| **End Customers** | Vendor’s customers | Browse, book, buy, track, pay, get support |

### Business model (how the platform makes money)

1. **Vendor subscriptions** — Free / Starter / Growth / Enterprise plans with feature & usage limits  
2. **Add-ons** — Extra stores, seats, SMS credits, premium themes, AI packs (later)  
3. **Marketplace commission** — Optional later when cross-vendor discovery exists  
4. **Payment processing fees** — Optional partner/gateway revenue share (later)

Vendors separately collect money from **their** customers via Razorpay / Stripe / PayPal (or their own gateway).

### Primary outcomes (why we build it)

- Vendors can go live via **Web App** (Admin + POS + portal + website) under their brand  
- All core operations are available through **stable REST APIs**  
- Platform owner can onboard, bill, suspend, and support thousands of tenants from Web Admin  
- Data stays isolated per tenant; branding/domains feel fully white-label  
- Modules can be enabled/disabled per industry and per subscription plan  
- System is implementable on **PHP 8.3 + HTML/JS + MySQL 8.4** by a product engineering team  
- APIs and Web App are completed **together** as the first full product release  

### In scope (first complete delivery)

- Multi-tenant SaaS core (tenant isolation, branding, domains, feature flags)
- **REST APIs** for all MVP modules (OpenAPI documented, PHPUnit covered)
- **Web App surfaces only:**
  - Platform Super Admin (Web)
  - Vendor Admin (Web)
  - POS (Web browser)
  - Customer Portal (Web)
  - Vendor white-label Website (Web)
- Core business modules (products, inventory, sales, services, CRM, orders, appointments, staff, reports, billing)
- Subscription billing for vendors
- Security, audit, backups, monitoring baseline
- Parallel tracks: API team + Web App team shipping one integrated MVP

### Out of scope (initial / deferred)

| Deferred item | When |
| --- | --- |
| **Native / white-label mobile apps** | After APIs + Web App MVP is complete |
| Mobile-specific UX / app stores | Later phase |
| Full marketplace (Amazon-like discovery) | Phase 3+ |
| Advanced AI agents / forecasting suite | Phase 3+ |
| Per-tenant dedicated databases | Scale / Enterprise |
| Microservices split | Only if monolith limits are proven |
| Custom ERP for enterprise corporations | Not the primary market |
| Storing raw card data | Never — use payment gateways |

### Product surfaces

| Surface | Priority | Purpose |
| --- | --- | --- |
| **APIs (`/api/v1`)** | **P0 — build now** | Contract for Web App now; mobile/integrations later |
| **Platform Admin (Web)** | **P0 — build now** | Operate the SaaS |
| **Vendor Admin (Web)** | **P0 — build now** | Run the business day-to-day |
| **POS (Web)** | **P0 — build now** | In-store / counter sales in browser |
| **Customer Portal (Web)** | **P0 — build now** | Orders, appointments, invoices, loyalty |
| **Vendor Website (Web)** | **P0 — build now** | Public branded storefront / booking site |
| **Mobile Apps** | **P2 — later** | Consume the same APIs after Web MVP |

### Success criteria (first complete delivery)

- APIs cover all MVP module operations and are documented in OpenAPI  
- Web App (Admin + POS + Customer Portal + Vendor Website) works end-to-end on those APIs  
- A new vendor can register, choose a plan, configure branding/domain, and start selling **from the Web App**  
- Retail vendor can manage products, stock, POS checkout, and basic reports **in browser**  
- Service vendor can manage services, staff, appointments, and customers **in browser**  
- Customers can browse/book/buy on the vendor’s branded **website / portal**  
- Super Admin can manage tenants, subscriptions, and platform health **on Web**  
- No tenant can read or mutate another tenant’s data  
- Mobile clients are **not required** to call this delivery “complete”  

### Design & build principles

- **APIs + Web App first** — complete these before mobile or marketplace clients  
- **Build in parallel** — API contracts and Web screens progress together  
- **API-first Web** — UI calls `/api/v1`; no duplicate business rules only in templates  
- **Modular** — enable only what the industry/plan needs  
- **White-label first** — vendor brand is the product experience  
- **Tenant-safe** — every business record carries and enforces `tenant_id`  
- **MVP-first** — ship Retail + Salon/Service before marketplace/AI  
- **Implementation-ready** — Pure PHP modular monolith the team can code from  
- **Secure & auditable** — JWT auth, RBAC, logs, soft deletes, encryption via gateways  

---

## Objective

You are a Principal Software Architect, SaaS Product Architect, ERP Architect, UX Architect, Database Architect, and Enterprise Solution Designer.

Your task is to design a production-ready, enterprise-grade, white-label Multi-Tenant Business Management Platform (**KarobariSuite**) that enables small and medium vendors to digitally manage every aspect of their business.

**First delivery constraint:** Design and prioritize **APIs + Web App only**. Mobile apps and other clients come later. Structure the blueprint so API and Web App work can run **in parallel** and produce one complete shippable product.

**Do NOT think of this as just an inventory system.**

Think of this as a combination of:

- Shopify
- Zoho One
- Odoo
- Square POS
- Lightspeed POS
- Salesforce CRM
- HubSpot CRM
- QuickBooks
- Fresha
- Mindbody
- WooCommerce
- Wix
- Stripe Dashboard

…combined into one platform specifically designed for small businesses.

The platform must be modular so that different industries can enable only the features they require.

Use the **Project Scope** section above as the source of truth for purpose, users, business model, in/out of scope, and success criteria.

## Technology Stack (Mandatory)

Use the following stack unless a justified exception is required for a specific subsystem:

| Layer | Technology |
| --- | --- |
| Backend API | **PHP 8.3+** (Pure PHP, **PSR-4** compliant) |
| Frontend | **PHP Templates + HTML5 + CSS3 + Vanilla JavaScript (ES2023)** |
| Architecture | **Modular Monolith (DDD-inspired)** |
| Database | **MySQL 8.4 LTS** |
| Web Server | **Nginx + PHP-FPM** |
| Search | MySQL Full Text → Meilisearch later |
| Authentication | **JWT + Refresh Tokens + API Keys** |
| Scheduler | **Cron + Queue Workers** |
| Email | SMTP + API Providers |
| Payments | **Razorpay, Stripe, PayPal** |
| Monitoring | **Monolog + Sentry** |
| Testing | **PHPUnit** |
| Documentation | **OpenAPI / Swagger** |
| Storage | **S3-compatible (Cloudflare R2)** |

### Architecture decisions for this stack

- **MVP tenant model:** Shared MySQL 8.4 database + `tenant_id` on every business table (row-level isolation).
- **Future option:** Separate MySQL schema/database per large tenant.
- **Architecture:** Modular monolith with DDD-inspired bounded contexts (e.g. Inventory, POS, Billing) — not microservices at day one.
- **Code style:** Pure PHP 8.3+, Composer + PSR-4 autoloading, PSR-12 coding standard, dependency injection container.
- **API:** REST JSON APIs for POS, mobile, and integrations; versioned (`/api/v1`); document with OpenAPI/Swagger.
- **Auth:** JWT access tokens + refresh tokens for users; API keys for integrations/webhooks.
- **UI:** Server-rendered PHP templates + HTML5/CSS3 + Vanilla JS (ES2023); SPA only where justified (POS terminal, website builder canvas).
- **White-label websites:** Themeable PHP/HTML templates per tenant (custom domain + branding).
- **Jobs:** Queue workers + cron for scheduled tasks (billing renewals, reminders, reports).
- **Observability:** Monolog for structured logs; Sentry for error tracking.
- **Storage:** Cloudflare R2 (S3-compatible) for media, exports, backups artifacts.
- **Testing:** PHPUnit (tenant isolation tests are mandatory).
- **Mobile apps:** API-first; native/Flutter apps are a later phase.
- **Do not** use Laravel/Symfony as the core framework unless explicitly approved later — stay Pure PHP + PSR-4 modular core.

## Core Vision

The platform is a **White Label SaaS Platform**.

- One platform
- Unlimited Vendors
- Unlimited Customers
- Unlimited Stores
- Unlimited Products
- Unlimited Services
- Unlimited Employees

Every vendor has their own isolated workspace while being managed centrally by the platform owner.

The platform owner sells subscriptions to vendors.

## Think Beyond Current Features

Do **NOT** simply organize the features listed below.

Instead:

- Think deeply
- Think like an enterprise architect
- Think about everything required to build a world-class SaaS platform

| If… | Then… |
| --- | --- |
| Something is missing | Add it |
| An architecture decision can improve scalability | Include it |
| Another module is required | Design it |
| Another micro-feature is required | Add it |

**Do not limit yourself.**

## Multi-Tenant SaaS Requirements

The platform **MUST** support:

- Unlimited tenants
- Tenant isolation
- Shared infrastructure
- Independent databases (future option)
- Custom domains
- Custom branding
- Custom themes
- Custom logos
- Custom colors
- Custom fonts
- White-label mobile apps
- White-label websites
- Tenant-specific configurations
- Tenant-specific tax rules
- Tenant-specific payment gateways
- Tenant-specific notification providers
- Tenant-specific currencies
- Tenant-specific languages
- Tenant-specific time zones
- Tenant-specific business hours
- Tenant-specific feature flags
- Tenant-specific subscription plans
- Tenant-specific storage
- Tenant-specific analytics
- Tenant-specific reports
- Tenant-specific APIs
- Tenant-specific integrations
- Tenant-specific workflows
- Tenant-specific automation
- Tenant-specific AI configuration

**Everything must be configurable per tenant.**

## User Types

The platform must support multiple user types.

### Platform Super Admin

Controls the entire SaaS platform.

**Can:**

- Manage vendors
- Manage subscriptions
- Approve vendors
- Suspend vendors
- Manage plans
- Manage themes
- Manage templates
- View platform analytics
- Manage payments
- Manage feature flags
- Manage global settings
- Manage marketplace
- Manage support
- Manage AI
- Manage integrations
- Manage backups
- Manage security
- View audit logs
- View all tenants
- View system health
- Manage announcements
- Manage onboarding
- Manage billing
- Manage taxes
- Manage emails
- Manage SMS
- Manage push notifications
- Manage domains
- Manage CDN
- Manage API keys
- Manage storage
- Manage jobs
- Manage queues
- Manage monitoring
- Manage fraud detection

### Vendor Owner

Owns one business.

**Can:**

- Manage business
- Manage employees
- Manage products
- Manage services
- Manage customers
- Manage suppliers
- Manage inventory
- Manage sales
- Manage accounting
- Manage reports
- Manage website
- Manage marketing
- Manage loyalty
- Manage automation
- Manage AI
- Manage branches
- Manage orders
- Manage appointments
- Manage delivery
- Manage integrations
- Manage subscription
- Manage settings

### Vendor Staff

Permission-based.

**Examples:**

- Manager
- Cashier
- Sales
- Inventory
- Warehouse
- Accountant
- Technician
- Support
- Marketing
- Delivery

### Customers

**Can:**

- Register
- Login
- Browse products
- Browse services
- Book appointments
- Place orders
- Track orders
- View invoices
- View loyalty points
- Write reviews
- Raise support tickets
- Chat
- Wishlist
- Wallet
- Membership
- Referral
- Notifications

## White Label Requirements

Each vendor must receive:

- Own Website
- Own Admin Panel
- Own POS
- Own Customer Portal
- Own Mobile App (future)
- Own Branding
- Own Domain
- Own Emails
- Own SMS
- Own WhatsApp
- Own Payment Gateway
- Own SEO
- Own Analytics
- Own Reports
- Own Theme
- Own Homepage
- Own Landing Pages
- Own Blog
- Own Policies
- Own Terms
- Own Privacy Policy
- Own Cookie Banner
- Own Contact Information

**Everything must appear as if it belongs entirely to that vendor.**

## Multi-Industry Support

The architecture must support multiple business types **without code changes**.

**Examples:**

- Retail
- Grocery
- Restaurant
- Salon
- Clinic
- Repair Shop
- Garage
- Electronics
- Furniture
- Fashion
- Jewelry
- Medical
- Pharmacy
- Pet Shop
- Gym
- Coaching
- Florist
- Bakery
- Hardware
- Construction
- Agriculture
- Professional Services
- Rental Business
- Home Services
- Consultants

Every industry should enable only the modules it needs.

## Required Modules

Design **ALL** modules in detail.

Use the following modules as the baseline.

*(Include everything below and expand each module significantly.)*

1. Dashboard
2. Product Management
3. Inventory
4. Sales
5. POS
6. Services
7. CRM
8. Supplier
9. Purchase
10. Staff
11. Roles & Permissions
12. Appointments
13. Orders
14. Accounting
15. Reports
16. Marketing
17. Customer Portal
18. Vendor Website Builder
19. E-commerce
20. Notifications
21. Loyalty
22. Help Desk
23. Multi-store
24. SaaS Billing
25. Integrations
26. AI
27. Mobile Apps
28. Security
29. Automation
30. Industry Modules
31. Marketplace

### For every module, provide:

- Objectives
- Submodules
- Features
- Workflows
- User Roles
- Permissions
- APIs
- Database entities
- Relationships
- Notifications
- Reports
- AI opportunities
- Automation opportunities
- KPIs
- Security considerations

## Platform Architecture

Design the complete architecture.

**Include:**

- Frontend
- Backend
- Admin Portal
- Vendor Portal
- Customer Portal
- Mobile Apps
- API Gateway
- Authentication
- Authorization
- Tenant Resolution
- Storage
- CDN
- Caching
- Queues
- Notifications
- Realtime
- Search
- AI
- Analytics
- Monitoring
- Logging
- Backup
- Disaster Recovery
- Scalability
- Rate Limiting
- Audit
- API Versioning
- CI/CD
- Infrastructure
- Deployment
- Cloud Architecture

## Database Design

Design a production-grade database.

- Think deeply
- Normalize properly

**Support:**

- Millions of vendors
- Millions of customers
- Billions of transactions
- Billions of products
- Billions of orders
- Billions of inventory movements

**Every table must include:**

- Primary Keys
- Foreign Keys
- Indexes
- Soft Delete
- Audit Columns
- TenantId
- CreatedBy
- UpdatedBy
- DeletedBy
- Versioning
- History where needed

Support future sharding.

## Security

Design enterprise security.

**Include:**

- OAuth
- JWT
- Refresh Tokens
- RBAC
- ABAC
- Multi-Factor Authentication
- Session Management
- Audit Logs
- Encryption
- Secrets Management
- Tenant Isolation
- Rate Limiting
- DDoS Protection
- OWASP
- GDPR
- Data Privacy

## AI Strategy

Design AI features across the platform.

- Inventory Forecasting
- Sales Prediction
- Dynamic Pricing
- AI Reports
- Smart CRM
- Marketing Generator
- Invoice OCR
- Receipt OCR
- Voice Ordering
- Voice Search
- Product Recommendation
- Fraud Detection
- Customer Segmentation
- Demand Forecasting
- Business Advisor
- AI Assistant

## Marketplace Vision

The platform should eventually evolve into:

**Amazon + Shopify + Urban Company + Booking.com**

Customers should eventually be able to:

- Discover Vendors
- Compare Vendors
- Compare Products
- Compare Services
- Book Services
- Purchase Products
- Track Delivery
- Track Service
- Leave Reviews
- Pay Online
- Multi-vendor Cart
- Marketplace Checkout
- Vendor Ranking
- Vendor Verification
- Nearby Vendors
- Location Based Search
- AI Recommendations

## Deliverables

Produce an enterprise-grade master design document containing:

- Vision
- Product Strategy
- SaaS Architecture
- White Label Architecture
- Multi-Tenant Architecture
- User Roles
- Complete Feature Breakdown
- Module Hierarchy
- User Flows
- Vendor Flows
- Customer Flows
- Admin Flows
- Database Design
- API Design
- Security Architecture
- AI Architecture
- Marketplace Architecture
- Mobile Strategy
- Deployment Architecture
- Scaling Strategy
- Disaster Recovery
- Monitoring
- Logging
- Analytics
- Billing System
- Subscription Management
- Roadmap (MVP → Enterprise)
- Risks & Mitigations
- Future Enhancements

## Module Depth Requirements

Do **not** list feature names only.

For **every module**, define concrete business rules, including:

- Create / Read / Update / Delete / Soft-delete behavior
- Status lifecycle (e.g. Draft → Active → Archived)
- Validation rules and edge cases
- Inventory impact (stock in / out / reservation)
- Tax, discount, and rounding rules
- Multi-store / multi-branch behavior
- Permission checks per action
- Notification triggers
- Report outputs
- Failure / rollback behavior
- Audit trail events

**Minimum depth examples required in the design:**

| Module | Must define |
| --- | --- |
| Inventory | Stock types, reservations, transfers, low-stock, adjustments, batch/serial (optional) |
| POS | Cart, tax, payments, partial pay, refunds, cash drawer, offline mode strategy |
| Orders | Order states, cancel, return, fulfillment, delivery assignment |
| Appointments | Slot booking, staff assignment, no-show, reschedule, deposits |
| Accounting | Chart of accounts, journal entries, invoices, payments, tax reports |
| CRM | Lead → customer pipeline, tags, notes, follow-ups |
| Purchase | PO → GRN → bill → payment |
| Billing (SaaS) | Plans, trials, renewals, dunning, feature gating |
| Website Builder | Pages, sections, SEO meta, custom domain DNS flow |

## Billing & Subscription Requirements

Design a complete SaaS billing system for the platform owner selling to vendors.

**Must include:**

- Plans & packages (Free / Starter / Growth / Enterprise)
- Feature gating per plan (module + usage limits)
- Trial period
- Monthly / yearly billing
- Seat / store / product / order usage limits
- Payment gateways (**Razorpay, Stripe, PayPal**; tenant can also connect own gateway for customer payments)
- Invoices & receipts for vendor subscriptions
- Proration on upgrade / downgrade
- Failed payment retries (dunning)
- Grace period → suspend → archive flow
- Coupons & promo codes
- Tax on subscription invoices
- Platform commission model (for marketplace phase)
- Billing webhooks & reconciliation
- Self-serve upgrade / downgrade in Vendor portal
- Super Admin override (manual activate / extend / waive)

**Separate clearly:**

1. **Platform billing** — vendor pays platform owner  
2. **Vendor commerce payments** — customer pays vendor  

## Roadmap / MVP Phases

Design must be phased. Do **not** treat all modules as equal priority.

### Phase 0 — Foundation (Weeks 1–4)

- Pure PHP 8.3 PSR-4 project structure + DDD-inspired module folders
- Multi-tenant core (`tenants`, `tenant_id`, middleware/resolver)
- Auth (JWT + refresh tokens + API keys) for Super Admin, Vendor Owner, Staff, Customer
- RBAC roles & permissions
- Tenant branding basics (logo, colors, domain)
- Audit columns + soft deletes
- Cron + queue workers + SMTP mail + Monolog/Sentry baseline
- OpenAPI/Swagger skeleton + PHPUnit bootstrap

### Phase 1 — MVP (Weeks 5–16)

Ship a sellable product for **Retail + Salon/Service** via **APIs + Web App only** (build both tracks in parallel):

**Track A — APIs**

- Auth (JWT + refresh + API keys)
- Tenant / branding / feature-flag APIs
- Module APIs: Dashboard data, Products/Services, Inventory, POS, Orders, Customers, Appointments, Staff/Roles, Reports, Notifications stubs, SaaS Billing
- OpenAPI docs + PHPUnit for each module

**Track B — Web App**

- Platform Super Admin (Web)
- Vendor Admin Panel (PHP templates + HTML/JS)
- POS (Web browser)
- Customer Portal (basic Web)
- One default white-label website theme

**MVP success criteria:** A vendor can register, subscribe, sell via Web POS/online, manage stock/appointments, and brand their portal — all through Web App backed by `/api/v1`. **No mobile app required.**

### Phase 2 — Growth

- Purchase / Suppliers
- Accounting lite
- Loyalty
- Marketing campaigns
- Multi-store
- Help Desk
- Integrations (WhatsApp, payment webhooks, shipping)
- Website Builder v2
- Advanced reports
- (Still Web App + APIs; no native mobile yet unless APIs are frozen)

### Phase 3 — Scale

- Full Accounting
- Automation engine
- AI assistants / forecasting
- Marketplace
- **White-label mobile apps** (first mobile clients — consume existing APIs)
- Advanced search
- Per-tenant DB option
- Advanced fraud / monitoring

### Phase 4 — Enterprise

- Custom SLA tooling
- Advanced ABAC
- Data residency options
- Deep ERP workflows
- Partner / reseller program

Every design recommendation must state which phase it belongs to.

## Non-Functional Requirements (Implementation Targets)

| Area | Target |
| --- | --- |
| Availability | 99.5% MVP → 99.9% Scale |
| API p95 latency | < 300ms for common reads |
| Concurrent POS terminals / tenant | 20+ (MVP), 200+ (Scale) |
| Backup | Daily full + binlog/PITR |
| RPO | ≤ 1 hour (MVP), ≤ 15 min (Scale) |
| RTO | ≤ 4 hours (MVP), ≤ 1 hour (Scale) |
| Tenant isolation | Hard fail if `tenant_id` missing/mismatched |
| Secrets | Env + encrypted storage; never in git |
| Compliance path | GDPR basics MVP; PCI via gateway (no raw card storage) |

## Implementation Readiness Requirements

The blueprint must be **implementation-ready** for a **Pure PHP 8.3 + PHP Templates/HTML/JS + MySQL 8.4** team.

**Must include:**

1. **Folder / module map** for PSR-4 modular monolith (e.g. `src/Inventory`, `src/Pos`, `src/Billing`)
2. **Core ERD** for MVP tables (names, key columns, FKs, indexes) on MySQL 8.4
3. **Tenant resolution flow** (domain / subdomain / header)
4. **Auth & permission matrix** (JWT/refresh/API key × role × action)
5. **API endpoint list** for MVP (`METHOD /path` + purpose) + OpenAPI stubs
6. **Key PHP template / HTML portal screens** (wireframe-level page list)
7. **Queue jobs + cron schedule list** (emails, webhooks, report generation, renewals)
8. **Config keys** per tenant (branding, tax, currency, locale)
9. **Seed / demo data strategy**
10. **Local setup steps** (Composer, `.env`, migrations, seed, PHP-FPM)
11. **Deployment outline** (Nginx, PHP-FPM, MySQL 8.4, queue workers, SSL, Cloudflare R2)
12. **Test strategy** (PHPUnit; tenant isolation tests are mandatory)
13. **Definition of Done** per MVP module
14. **Risks** specific to Pure PHP modular monolith + shared MySQL tenancy
15. **Monitoring setup** (Monolog channels + Sentry)

### Acceptance criteria format

For each MVP feature, write:

- **Given** …  
- **When** …  
- **Then** …

Example:

- Given a vendor staff user without `inventory.adjust` permission  
- When they call stock adjustment API  
- Then the request is rejected with 403 and no stock row changes  

## Integrations (Minimum)

Design adapters for:

- **Payments:** Razorpay, Stripe, PayPal (platform + optional vendor-owned)
- **SMS:** Twilio / MSG91
- **Email:** SMTP + API providers
- **WhatsApp:** Meta Cloud API (Phase 2)
- **Maps / Geo:** for nearby vendors (Marketplace phase)
- **Storage:** Cloudflare R2 (S3-compatible)
- **Search:** MySQL Full Text (MVP) → Meilisearch (later)
- **Webhooks:** outbound tenant webhooks (Phase 2)
- **Monitoring:** Monolog + Sentry

## Expected Quality

Do **not** provide a high-level summary.

Produce a deep, enterprise-grade blueprint suitable for building a commercial SaaS product on **PHP 8.3 (Pure PHP, PSR-4) + PHP Templates/HTML5/CSS3/Vanilla JS + MySQL 8.4 LTS**.

Every recommendation should prioritize:

- Scalability
- Modularity
- Tenant isolation
- Configurability
- Maintainability
- Extensibility
- Security
- **Implementation readiness** (a mid-level Pure PHP team can start coding from the doc)
- **Phased delivery** (MVP first, marketplace/AI later)

The design should support thousands of vendors today on a DDD-inspired modular PHP monolith + shared MySQL 8.4, with a clear path to millions later (read replicas, partitioning/sharding, optional per-tenant DB, Meilisearch) without rewriting the product from scratch.

**Output must be actionable:** ERDs, OpenAPI specs, permission matrices, phase tags, PHPUnit plans, and acceptance criteria — not slogans.