# Next Phase Development Plan

Date: July 2, 2026
Product: VejalNai Chatbot
Goal: Move from strong beta to production candidate

## North Star

VejalNai should become a reliable omnichannel support system where AI answers safe known questions, humans can take over complex conversations, and every enabled channel behaves as a complete two-way channel.

## Phase 1 Objective

Stabilize correctness before expanding features.

The next phase should prioritize:

1. Delivery correctness.
2. Authorization correctness.
3. Webhook reliability.
4. Widget session security.
5. AI/human operations workflow.
6. Production deployment gates.

## Immediate Release Blockers

| Priority | Work item | Why it matters |
| --- | --- | --- |
| P0 | Outbound channel delivery | Agents must actually reach Facebook and WhatsApp customers. |
| P0 | Webhook idempotency | Provider retries must not duplicate conversations/messages. |
| P0 | RBAC enforcement | Privileges must mean something across the whole app. |
| P1 | Bangla mojibake fix | Target-language support must be trustworthy. |
| P1 | Widget signed sessions | Public chat history needs stronger protection. |
| P1 | Production signature guard | Meta webhooks should require SHA-256 before launch. |
| P1 | Pint/CI gate | Release quality should be automated. |

## Sprint 0: Stabilization And Gates

Duration: 2 to 4 days

Tasks:

- Run Pint and commit style fixes.
- Fix corrupted Bangla command and response text.
- Move user-facing bot strings into translation files.
- Add CI script that runs:
  - `vendor\bin\phpunit --configuration phpunit.xml`
  - `vendor\bin\pint --test`
  - PHP lint for app/routes/database/resources/tests/config/bootstrap
  - `php artisan config:cache`
  - `php artisan route:cache`
  - `php artisan view:cache`
- Add policies or dedicated FormRequest authorization for:
  - Appearance update: `customize_widget`
  - Channel update/delete: `manage_channels`
  - Conversation reply: `reply_to_customers`
  - Conversation message poll: `view_inbox`
  - Unknown-question resolve: `train_ai`
  - Callback complete: `manage_callbacks`
- Add negative authorization tests for each write route.

Acceptance criteria:

- PHPUnit, Pint, lint, config cache, route cache, and view cache pass.
- A user without a privilege receives 403 for the protected action.
- Bangla name command and response are valid UTF-8 and tested.

## Sprint 1: Message Delivery And Idempotency

Duration: 1 to 2 weeks

Data model tasks:

- Add provider delivery columns to `messages`:
  - `provider`
  - `provider_message_id`
  - `provider_event_id`
  - `provider_timestamp`
  - `delivery_status`
  - `delivery_error`
  - `delivered_at`
- Add unique index for provider inbound idempotency.
- Add `channel_delivery_attempts` table if detailed retry logs are needed.

Backend tasks:

- Create `ChannelMessageSender` service.
- Create provider adapters:
  - `WebWidgetSender`
  - `FacebookMessengerSender`
  - `WhatsAppCloudSender`
- Queue outbound delivery jobs.
- Add retry and backoff.
- Record delivery results.
- Skip duplicate inbound webhook events safely.
- Add tests for duplicate Facebook and WhatsApp payloads.

UI tasks:

- Show pending/sent/failed state beside agent messages.
- Add retry button for failed messages.
- Show channel health in conversation sidebar.

Acceptance criteria:

- Web, Facebook, and WhatsApp customers receive human replies.
- Failed sends are visible and retryable.
- Duplicate webhook payloads do not create duplicate messages or bot replies.

## Sprint 2: Production Widget And SDKs

Duration: 1 week

Widget tasks:

- Replace plain `sessionStorage` visitor identity with server-issued signed widget session token.
- Add session expiry and rotation.
- Add endpoint rate limiting by widget key, origin, IP, and session.
- Require allowed origins in production readiness.
- Add widget E2E tests for desktop and mobile.
- Add contrast validation for custom colors.

SDK tasks:

- Add `GET /api/widget/messages` support to Android and iOS clients.
- Add typed success/error models.
- Add timeout/retry configuration.
- Add examples for Flutter and React Native as first-class docs.
- Add package/distribution plan if these will be published.

Acceptance criteria:

- Widget history cannot be fetched with only a guessed visitor id.
- Public widget endpoints are rate limited.
- SDK clients can send and fetch history with typed responses.

## Sprint 3: AI Operations And Human Review

Duration: 1 to 2 weeks

Tasks:

- Add AI Monitor page for users with `monitor_ai`.
- Show bot response, matched intent, matched phrase, confidence, and response template.
- Add approve/edit/escalate controls.
- Add `train_ai` workflow for unknown questions.
- Add typo correction review UI.
- Add report metrics:
  - Bot answered count
  - Clarification count
  - Handoff count
  - Unknown-question count
  - Human response time
  - Failed delivery count

Acceptance criteria:

- Supervisors can review bot output without code access.
- Training actions are restricted to `train_ai`.
- Corrections improve future matching and are auditable.

## Sprint 4: Production Onboarding And Admin Health

Duration: 1 week

Tasks:

- Add production readiness checklist page.
- Add channel connection test buttons.
- Validate Meta credentials and webhook subscription.
- Require SHA-256 webhook signature mode for production readiness.
- Add audit log for:
  - Team changes
  - Privilege changes
  - Channel changes
  - Appearance changes
  - Human replies
  - Training changes
  - Callback completion
- Add team invitation flow instead of manual password creation.
- Add password reset/email verification if public use is expected.

Acceptance criteria:

- Admin can see if the workspace is launch-ready.
- Sensitive changes are auditable.
- New team members can be invited safely.

## Technical Architecture Changes

Recommended new services:

- `App\Services\Channels\ChannelMessageSender`
- `App\Services\Channels\FacebookMessengerClient`
- `App\Services\Channels\WhatsAppCloudClient`
- `App\Services\Webhooks\WebhookIdempotencyGuard`
- `App\Services\Widget\WidgetSessionIssuer`
- `App\Services\Audit\AuditLogger`

Recommended new jobs:

- `SendChannelMessage`
- `ProcessMetaWebhookEvent`
- `RefreshChannelHealth`

Recommended new policies:

- `ConversationPolicy`
- `CallbackRequestPolicy`
- `UnknownQuestionPolicy`
- `ChannelIntegrationPolicy`
- `OrganizationAppearancePolicy`
- `MembershipPolicy`

## Definition Of Done

A next-phase feature is done only when:

- Backend behavior works.
- UI state reflects real backend state.
- Authorization is enforced.
- Tests include happy path and denial/failure path.
- Audit log exists for sensitive actions.
- Documentation is updated.
- CI gates pass.

## Recommended Implementation Order

1. Fix Pint and Bangla mojibake.
2. Add policies/FormRequest authorization.
3. Add idempotency fields and tests.
4. Add outbound channel sender and jobs.
5. Add delivery status UI.
6. Harden widget sessions and rate limits.
7. Add AI Monitor workflow.
8. Add production readiness page and audit log.

## Stop-Doing List For This Phase

- Do not add more channel names until Facebook and WhatsApp are fully two-way.
- Do not market SDK support as complete until SDKs fetch history and handle typed errors.
- Do not call the product production-grade until P0s are closed.
- Do not rely on UI hiding alone for permissions.
