# Phase 5: Unified Chat-Native UX & Complete Homepage Experience

## Status (29 July 2026): **In Progress — ≥19.0.1.3.12 web access + a11y + growth**
Shipped toward complete chat UX:
- **Web photo login (1.3.11):** homepage **Photo login (web)** → `/businessite/login` (phone, industry, occupation, mother tongue, selfie). Support **Access** tasks grant/block/fraud. Timed `bs_web_access` session; cron expire. Logged-in/linked `/` and `/businessite` → chat (`?public=1` escape). **Logout → `/businessite?logged_out=1`** (public homepage, not login form).
- **Accessibility bar (1.3.12):** fixed bottom bar on website routes — **language switcher** (localStorage + cookies), **Read page** TTS, **Stop**, **Voice nav** (go home, photo login, register, open chat, apps, roadmap, mall, read page, stop, logout, language …). Aim: usable for all human abilities.
- Preferred AI connect + sponsorship in chat (web + mobile), **validated keys**, auto-fallback to platform **Groq**
- Inclusive registration (Education plan, dial codes, full country/industry/occupation/language catalogs) + **mother tongue**
- Rich media / document / shopping
- **Chat payments**: default **PayFast**, preferred gateway on client, `pay_now` direct to gateway (**no delivery address form**)
- Banking / **virtual private banker** roadmap scaffold (chat strings; rails later)
- **`businessite_messaging`**: Odoo Discuss DMs, groups, public channels
- **Chat-first** commands (`help messaging`, `dm +27…`, `find a doctor near me`, `emergency …`, `start mesh`, …)
- Mesh protocol (BLE UUID + WiFi `BSITE-`) store-and-forward envelopes
- **Email from chat (1.6.19 → 1.2.75)**:
  - `email to` name **or** phone **or** `a@b.com` (subject/body multi-step; **not** wallet)
  - Registered BusinesSite users → Human+AI **Mailing Support Queue** (platform mailbox `name_uuid@…`)
  - Unregistered external addresses → **direct send** + BusinesSite Emailing **advert** (native-language voice mail)
  - Admin: full **subject/body preview**, **attachments** included on send, pick recipient by profile
  - `reply email #ID`, `my mailbox`, `check my email`, `listen to email #ID`, `my mother tongue is …`
  - Mailcow IMAP inbound; **IPv4-only** outbound (Gmail 550-5.7.1 fixed)
- **User guides in chat**: `guides` / `guide isp-domains` / `guide eshop` / `guide email` / `guide mobile` / `guide media` / `guide notifications` (+ PDF)
- **Push/share (1.6.12 → 1.6.32)**: WorkManager poll chain + battery unrestricted + high-importance channel when app closed; hub publish queues `app_update` (product-line TA5 vs RC1). FCM when `businessite.fcm_server_key` set.
- **Web login QR (1.6.13 → 1.2.85)**: in-app `login to web` / `scan qr` → browser QR (`businessite://web-chat-sync`).
  - Poll + **localStorage/cookie** `bs_web_session` so homepage and chat share one token.
  - On link: open **full** `businessite_chatbot_dashboard` (not yellow Demo Mode shell) with phone name in header, chips, voice, **📎 Photo**.
  - **Unlink phone** header control + `/businessite/unlink_web_chat_session?redirect=1` delinks browser only.
  - **Bidirectional history**: `/businessite/chat/history` + web poll ~3s + mobile sync; turns persisted on all intents.
  - Support: `/businessite/support/profile` QR for mobile desk. Guides updated.
- **Web product media (1.2.85)**: `add product NAME photo` opens **PC file chooser** synchronously; **📎 Photo** button + Attach photo chip; upload via `/businessite/chat/upload_document` (public ACL fixed for `ir.sequence`); applies gallery to shelf **without** auto support ticket. Mobile multi-select unchanged.
- Mobile hubs: **TA5 1.6.32+41** + **RC1 1.7.10+11** / **TA8 1.8.0+1** (32/64 only).
- **bi_payfast_payment_acquirer** + shelf Buy me now / cart checkout direct to PayFast
- **Profile via chat (19.0.1.3.x)**: `my profile`, name/surname, multi phone/email, visibility; **primary email cannot be removed**; **≥1 phone always** (primary required)
- **Groups**: `create group NAME with +27…`, invite, post, `my groups`
- **Member vs guest price**: `set member discount 10%`; checkout phone gate for registered discount
- **Growth / path to profit (19.0.1.3.1)**: `wish` / `requirement list`; **cost product …** margins + break-even; industry/role **request queues**; **TA9** `preorder offer` scaffold
- Same growth commands on **web chat and mobile** (shared `/businessite/chat/message` API)
- **Mother-tongue OS (19.0.1.3.2):** `response_language_mode` = english (default) / mother_tongue / both; chat replies localized; first-time language notice; voice STT uses **registration languages**; if uncertain → no invented text, `lang_und` queue; support queues **`lang_en` / `lang_zu` / …**; agent gets translation+instructions in their tongue; user receives reply in preferred mode (French↔Zulu style bridge)

### TA track note (24 July 2026)
- **TA5 is Done** as the general voice-first hub foundation for this phase.
- Product sequence: **TA5 → TA8 (next, Colourcraft Auto)** → **TA9 PreBooking/Pre-Order** (scaffold live) before **TA6 Sensi** / **TA7 NATIVEnvoy**.
- TA6/TA7 reuse TA5 chat; TA8 hardens TA5 into full commercial Chat OS. See [TA_TRACK_DEPENDENCIES.md](TA_TRACK_DEPENDENCIES.md).

Still open for full Phase 5 “complete homepage product”: full wallet ledger, seller storefronts depth, live banking providers, optional **FCM/APNs** true kill-state push, TA9 prepaid PayFast deposits, optional native email contact-picker polish.

### Maintenance rule
**Every new feature or APK build must update this phase doc (status bullets), `/businessite/roadmap` phase text in `controllers/main.py`, and UAT steps in `data/uat_launch_releases.xml`.** See [ROADMAP_UAT_MAINTENANCE.md](ROADMAP_UAT_MAINTENANCE.md).

## Objectives
- Make the intelligent chat the primary, unified entry point for all 4 user layers (Core Team, Client/Human, Support Provider, Business).
- Deliver fully layer-aware experiences: core team tools, client dashboards, support queues, business operations — all driven from chat + voice.
- Integrate rich media (photos, videos, rich cards), apps hub, payments, Odoo Discuss, and voice-first AI into one seamless UX.
- Transform the homepage into the complete, living product (real-time stats, stories, CTAs, chat as hero).
- Support rich HTML/markdown rendering in chat bubbles for app descriptions, product posts, and adverts.
- Enable in-chat media capture (take picture/selfie, record video) for shop registration, product posting, video adverts.
- Enable document upload (any format incl photos/PDFs) in chat for seller catalogs, POs, invoices.
- Full shopping: sellers (artists/designers/beauty/health resellers/retailers) register (as businessite.client + res.company shop), users search products/suppliers, view catalogs+prices, buy+pay (Payfast) in chat.
- Payfast integrated to Odoo website_sale (ecommerce) + point_of_sale for all registered shop companies.
- Shops created as res.company; seller online shops via website module (core team task to flesh storefronts per seller).
- Phases + layer/role tasks modeled as Odoo project.project + project.task (with tags for Data/System/User/Security/App teams and Architect/Analyst/Admin/Developer roles) for recruitment/onboarding.
- Cover the 5 layers (Data, System, User, Security, App) with concrete tasks per role.

## Key Technical Deliverables
- **Chat router** (chat.py + Dart _processCommand / _get_chatbot_response):
  - Layer detection from profile (core_team, is_support_provider, business_id, etc.).
  - Route messages, commands ("show apps", "join X", "take picture", "send money"), and AI fallback.
  - **Preferred AI Engines + Sponsorship**: Helpers allow users to say/voice "connect my ai to [engine] key ...", "sponsor +phone with my ai". Stores per-client preferred (provider, key, model, base_url). Sponsors share subs (ai_sponsor_id). Any engine supported. Fallbacks. Integrated into all AI uses (chat, training, support tasks, translate/instruct).
  - Full Odoo module-specific AI training/assessments/qualification in chat (web+mobile parity) for support providers. Language routing + AI assists.
- Rich message types: text, voice, image, video, app_card, rich_html, payment_link, wallet_transfer.
- Media capture in chat UI (reuse/extend PhotoCaptureWidget + camera plugin for photo/video).
- Upload media to Odoo (voice.message or new attachment model) + display in bubbles.
- Homepage: chat as central hero, layer-specific sections, live stats from clients/apps/UAT.
- App descriptions and product posts use t-raw / rich rendering (no escaped HTML tags in chat).
- Payment/wallet commands: "share payment link for SchoolLMS", "transfer 50 to @user", "pay invoice".
- Integration with existing UAT, mobile publish, subscription fees, hybrid networking (direct for media/downloads).

## Homepage / Roadmap UX Impact
- Chat becomes the hero and main navigation.
- "Apps Hub", "Earn as Support", "Business Tools", "Core Team" all accessible via natural language + buttons.
- Rich cards for apps/products render beautifully (bold, bullets, emojis).
- Media capture flows for shop owners to post products/adverts directly in chat.

## 5-Layer Implementation Breakdown

### Data Layer
- **Architect**: Design unified message/attachment models (extend voice.message or new chat.message with binary fields for photo/video, links for payments).
- **Analyst**: Define data flows for rich content (HTML → rendered), media metadata (type, url, caption), wallet transactions (from/to, amount, status).
- **Admin**: Seed sample rich app data, media examples, test wallet users; configure access.
- **Developer**: Implement media upload endpoints, rich content storage, transaction logging in Odoo (businessite.voice.message or dedicated model).

### System Layer
- **Architect**: Central chat service with layer routing, media handling, payment/wallet integration points.
- **Analyst**: Workflow for "take photo" → capture → upload → attach to message/product/shop; payment link generation.
- **Admin**: Set up crons for media processing, payment reminders; monitor hybrid networking for media transfers.
- **Developer**: Dart camera integration in chat (commands trigger CameraController), upload via OdooService, render in bubbles; backend _get_chatbot_response + new endpoints for media/payment.

### User Layer
- **Architect**: Chat-first UX: natural commands ("take selfie for my shop", "record video advert", "send 100 to supplier"), rich bubbles, media preview.
- **Analyst**: User stories per layer (shop owner posts product with photo/video, support shares invoice link, business transfers funds).
- **Admin**: Onboard users to media features; create sample shops/products for testing; train on wallet commands.
- **Developer**: UI for capture (selfie mode, video recording with preview), send as chat message; display rich HTML (b> 
 • etc.) using RichText or html widget; wallet UI scaffold (amount, recipient, send button → backend stub).

### Security Layer
- **Architect**: Media privacy (only to intended recipients/layers), payment auth (wallet balance, KYC for transfers), consent for capture.
- **Analyst**: Risks: media abuse, payment fraud, profile data in rich posts; compliance for financials.
- **Admin**: Groups/ACL for who can send/receive media/payments; audit logs; review grants for paid apps.
- **Developer**: Permission checks before capture/upload; secure upload (auth required); sign/validate payment links; integrate with existing subscription fee checks.

### App Layer
- **Architect**: Chat as app hub + financial layer: rich app cards, in-chat product posting, wallet transfers as first-class messages.
- **Analyst**: App-specific data (shop products with media, advert videos), integration with mobile publish + fees.
- **Admin**: Publish apps with fees; manage wallet feature flags; seed demo shops/adverts.
- **Developer**: Commands in chat_screen: if (lower.contains('take picture') || lower.contains('take selfie')) _captureAndSend(isVideo: false, selfie: ...); similar for video. Extend _showAvailableApps to support rich rendering. Add _handleWalletCommand for "share payment", "transfer". Backend support for attachments in chat_message.

## Dependencies
- Camera plugin (already in pubspec).
- Existing Odoo chat (chat.py, voice.message), mobile.app (fees), client models.
- Hybrid networking for media when offline.
- Payment subsystem (Payfast, SCode, platform billing) + future wallet model.

## Success Criteria
- "show apps" renders rich HTML descriptions (bold, bullets, no raw tags) in nice bubbles/cards.
- User can say "take picture for my shop", capture, post as product/advert.
- "record video advert" works similarly.
- "send 50 to @supplier" or "share payment link for SchoolLMS" creates link/transfer (scaffolded now, full in financial phase).
- Homepage feels complete with chat at center.
- All 4 layers experience unified chat UX.
- UAT steps cover media capture, rich rendering, wallet commands.

## Further Reading
- UAT for Chat & Mobile features
- Phase 1 (Core/SLUG), Phase 6 (UAT)
- Mobile publish + fee support
- Existing chat and voice_message models
- Roadmap teaser on homepage

## Detailed Tasks by Layer and Role (for full implementation)

### Data Layer
- **Architect**: Extend or design `voice.message` / new `businessite.chat.message` + attachment models: add Binary fields (or ir.attachment links) for photo/video, mime_type, thumbnail, caption, linked_resource (shop_id/product_id/advert_id), sender_layer. Support storing original rich HTML + rendered version for descriptions and posts.
- **Analyst**: Define schemas, validation (size limits on media <10MB for chat, sanitize rich HTML to allowed tags only), audit fields for wallet tx (from_user, to_user, amount, status, ref). Map how app.description (Html) flows to mobile catalog JSON without escaping loss.
- **Admin**: Seed demo data: 2-3 rich app descriptions with , 
,