# KarobariSuite — Web Pages Reference

All paths are relative to your app origin (e.g. `http://localhost:8080` when running `composer serve`).

| Area | Base path |
|------|-----------|
| Marketing & vendor app | `/web/` |
| Public storefront | `/site/` |
| Marketplace discover | `/discover.php` |
| REST API | `/api/v1/` |

---

## Entry & redirects

| URL | Who | Purpose |
|-----|-----|---------|
| `/` | Public | Redirects to `/web/` |
| `/web/` | Public | Marketing homepage — product pitch, CTAs to sign up or explore |

---

## Public marketing site

Static marketing pages (no login required). Loaded from `/web/*.php` with shared marketing chrome.

| URL | Purpose |
|-----|---------|
| `/web/index.php` | **Home** — hero, feature highlights, links to register and product tour |
| `/web/product.php` | **Product** — module overview (POS, inventory, CRM, APIs, multi-tenant) |
| `/web/solutions.php` | **Solutions** — industry playbooks (retail, salon, clinic, platform operators) |
| `/web/pricing.php` | **Pricing** — SaaS plan cards (loads plans from `/api/v1/billing/plans`) |
| `/web/compare.php` | **Compare** — positioning vs Square / Shopify-style stacks |
| `/web/faq.php` | **FAQ** — common questions about plans, branding, payments |

Marketing nav also links to **Demo store**: `/site/?slug=demo-shop`

---

## Authentication

| URL | Who | Purpose |
|-----|-----|---------|
| `/web/login.php` | Public | **Sign in / Register** vendor or platform admin; stores JWT in `localStorage` |
| `/web/oauth-callback.php` | Authenticated flow | OAuth return handler — saves tokens and redirects to dashboard |

After login, vendors land on `/web/dashboard.php`. Unauthenticated access to vendor pages redirects to login.

---

## Vendor workspace (authenticated)

Requires vendor JWT. Sidebar in `_layout_top.php`; some items hidden by **plan entitlements** (`data-module`) or **industry profile**.

### Core operations

| URL | Purpose |
|-----|---------|
| `/web/dashboard.php` | **Dashboard** — sales summary, quick stats; platform admins see tenant list & approvals |
| `/web/onboarding.php` | **Onboarding** — first-run checklist (branding, catalog, go-live) |
| `/web/pos.php` | **Point of Sale** — in-browser POS: cart, checkout, held carts, receipts, refunds |
| `/web/orders.php` | **Orders** — list orders, view receipt, record payment |
| `/web/products.php` | **Products** — catalog CRUD, pricing, SKU |
| `/web/services.php` | **Services** — bookable services (duration, price, tax) |
| `/web/inventory.php` | **Inventory** — stock levels, adjustments |
| `/web/customers.php` | **Customers** — CRM customer records |
| `/web/appointments.php` | **Appointments** — calendar list, slots, book/reschedule, complete/no-show |
| `/web/stores.php` | **Stores** — multi-location branches, stock transfers |
| `/web/staff.php` | **Staff** — vendor staff users |
| `/web/roles.php` | **Roles & permissions** — RBAC roles, assign users |

### Finance & purchasing

| URL | Purpose |
|-----|---------|
| `/web/suppliers.php` | **Purchasing** — suppliers, purchase orders, receive stock |
| `/web/accounting.php` | **Accounting** — P&L, trial balance, journals, invoices, GST/VAT, AR/AP aging, period close |
| `/web/billing.php` | **Subscription billing** — tenant SaaS plan, Razorpay checkout, invoices, cancel |
| `/web/reports.php` | **Reports** — sales, growth, product performance, staff sales, inventory valuation (platform admins see plan management) |

### Growth & customer experience

| URL | Purpose |
|-----|---------|
| `/web/loyalty.php` | **Loyalty** — points rules, adjust balances, redeem |
| `/web/campaigns.php` | **Marketing** — email/SMS campaign drafts and send |
| `/web/tickets.php` | **Help desk** — support tickets and replies |
| `/web/website.php` | **Website builder** — pages, sections, preview, publish |
| `/web/blog.php` | **Blog** — categories and posts for storefront |
| `/web/delivery.php` | **Delivery zones** — local delivery fees and coverage |
| `/web/leads.php` | **CRM pipeline** — leads and deal stages |
| `/web/marketplace.php` | **Marketplace listing** — publish vendor profile for discover |
| `/web/search.php` | **Search** — unified search across products, customers, orders, tickets |

### Automation & intelligence

| URL | Purpose |
|-----|---------|
| `/web/automations.php` | **Automations** — trigger → action rules |
| `/web/ai.php` | **AI insights** — revenue forecast, recommendations, NL query, OCR, fraud, voice |
| `/web/workflows.php` | **ERP workflows** — multi-step approvals |

### Compliance & security

| URL | Purpose |
|-----|---------|
| `/web/sla.php` | **SLA** — policies, incidents, respond/resolve |
| `/web/abac.php` | **ABAC** — attribute-based access policies |
| `/web/residency.php` | **Data residency** — region / storage class settings |
| `/web/security.php` | **Security** — MFA (TOTP) setup |
| `/web/gdpr.php` | **GDPR** — export, erasure, consent |
| `/web/monitoring.php` | **Monitoring** — fraud/ops alerts; platform health for admins |
| `/web/integrations.php` | **Integrations** — outbound webhooks (order events) |
| `/web/notifications.php` | **Notifications** — notification outbox queue |

### Settings

| URL | Purpose |
|-----|---------|
| `/web/settings.php` | **Store settings** — branding, custom domain, Razorpay, email SMTP, business hours, industry profile, analytics (GA/Pixel), theme presets |

**Storefront shortcut** (from vendor nav): `/site/?slug={your-tenant-slug}` — opens your public store in a new tab.

---

## Platform admin only

Visible when logged in as `platform_super_admin` (`data-nav="platform"`).

| URL | Purpose |
|-----|---------|
| `/web/partners.php` | **Partners** — reseller program, attach tenants, commissions |
| `/web/dunning.php` | **Dunning** — failed billing queue, restore tenants |
| `/web/ops.php` | **Platform ops** — backups, queue depth, SLO summary, run/verify backup |
| `/web/audit.php` | **Audit logs** — platform-wide audit trail |

Platform admins use the same `/web/dashboard.php` and `/web/reports.php` with elevated views.

---

## Customer-facing storefront

Public pages for end customers. Tenant selected via `?slug=` query param (default: `demo-shop`).

| URL | Purpose |
|-----|---------|
| `/site/?slug={slug}` | **Storefront** — browse catalog, cart, checkout (Razorpay/COD), wishlist, reviews, order tracking, book appointments |
| `/site/page.php?slug={slug}&page={page}` | **Policy / CMS page** — published website pages (e.g. `terms`, `privacy`, `refunds`) |
| `/web/portal.php?slug={slug}` | **Customer portal** — sign in, cart, appointments, loyalty, orders, membership, delivery tracking, support tickets |

### Storefront query parameters

| Param | Example | Effect |
|-------|---------|--------|
| `slug` | `?slug=my-shop` | Which tenant store to load |

### Portal extras (same `slug` param)

- Membership plans & subscribe  
- Delivery tracking by UUID  
- Order history & track by order number  

---

## Marketplace discover

| URL | Who | Purpose |
|-----|-----|---------|
| `/discover.php` | Public | **Multi-vendor marketplace** — search vendors by city/category, map, AI recommendations, voice search, unified cart & checkout across vendors |

Uses `/api/v1/marketplace/*` (not vendor JWT).

---

## Partner portal

| URL | Who | Purpose |
|-----|-----|---------|
| `/web/partner-portal.php` | Partners | Separate login for reseller partners — dashboard and commission history |

Uses `/api/v1/partner-portal/*`.

---

## Page → primary API mapping

Vendor pages call `/api/v1/...` via `Karobari.apiFetch()` in `/web/assets/{page}.js`. Storefront/portal call `/api/v1/storefront/{slug}/...`.

| Page | Main API prefixes |
|------|-------------------|
| `dashboard.php` | `/dashboard/summary`, `/platform/*` |
| `pos.php` | `/products`, `/services`, `/orders/checkout`, `/pos/held-carts` |
| `settings.php` | `/settings/*`, `/industry/me` |
| `portal.php` | `/storefront/{slug}/*` |
| `discover.php` | `/marketplace/*` |
| `pricing.php` | `/billing/plans` |

Full API catalog: `openapi/openapi.json` (regenerate with `composer openapi`).

---

## Access summary

| Role | Typical entry |
|------|----------------|
| Visitor | `/web/`, `/web/pricing.php`, `/discover.php` |
| Vendor owner/staff | `/web/login.php` → `/web/dashboard.php` |
| Platform admin | Same login → dashboard with tenant management |
| Customer | `/site/?slug=…` or `/web/portal.php?slug=…` |
| Partner | `/web/partner-portal.php` |

---

## Not separate pages (assets only)

These support pages but are not browsable routes:

- `/web/assets/*.js` — page-specific API clients  
- `/web/_layout_top.php`, `_layout_bottom.php` — vendor shell  
- `/web/_marketing_top.php`, `_marketing_bottom.php` — marketing shell  

---

*Last updated: reflects routes under `public/web/`, `public/site/`, and `public/discover.php`.*