Docs/Developer Notes

Developer Notes

This page explains the architecture rules behind the marketplace release. Use it when extending the product, building add-ons, reviewing workspace isolation, or preparing support notes.

1) Laravel Core Is The Source Of Truth

The core owns these systems

Workspaces, users, roles, and selected workspace context.
Billing, subscriptions, invoices, plans, usage, and gateway logs.
Conversations, messages, tickets, leads, CRM records, and reports.
AI settings, prompts, knowledge sources, QA logs, and handoff events.
Email inbox, channel connections, connector registry, webhooks, audit logs, and exports.

Addons embed, identify, sync, and pass context. They must not duplicate AI, billing, CRM, tickets, or conversations.

2) Canonical Tables

Active support-desk behavior should use canonical aibot_* tables. If a legacy table exists, keep it as compatibility only unless a specific feature intentionally mirrors data.

Area	Canonical behavior
Conversations and messages	Workspace-scoped support activity.
Tickets and CRM	Contacts, companies, leads, deals, stages, and support tickets.
AI	Provider config, QA logs, prompts, diagnostics, usage, and handoff.
Connectors	Installed package state, normalized events, sync status, and health.
Enterprise	Audit logs, rate limits, onboarding, exports, and readiness.

3) Workspace Scoping

Any query that reads customer/support data should normally filter by workspace. Workspace isolation is a core SaaS trust requirement and should be treated as a regression risk in tests.

Workspace-scoped data

Users, agents, widgets, API tokens, and webhooks.
Conversations, tickets, contacts, companies, deals, and leads.
Knowledge sources, AI usage, billing records, and connector events.
Audit logs, exports, reports, and demo data.

Important tests

Workspace A cannot see Workspace B conversations.
API tokens only access their own workspace.
Exports do not leak cross-workspace records.
Demo reset only touches known demo workspaces.

4) Queue And Scheduler

Production installs should run a persistent queue worker and the Laravel scheduler. Do not rely on synchronous processing for AI, sync, webhooks, exports, or notifications.

php artisan queue:work --tries=3 --timeout=120
* * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1

Email polling, reminders, webhook delivery, exports, and push notifications can appear broken if the queue or scheduler is missing.

5) AI Engine Boundary

Only the Laravel core should call the AI provider. Addons must not store OpenAI/provider keys and must not run inference directly. This keeps billing, usage, citations, QA, and handoff centralized.

AI usage should increment plan counters.
Low-confidence answers should create handoff events.
Prompt versions should be restorable.
Knowledge diagnostics should reveal stale, failed, empty, and low-match sources.

6) Connector Contract

GET   /api/v1/connectors/bootstrap
POST  /api/v1/connectors/install
POST  /api/v1/connectors/events
PATCH /api/v1/connectors/{connectorKey}/heartbeat

Normalized connector event example

{
  "source": "woocommerce-connector",
  "event_name": "woocommerce.order.issue",
  "external_id": "order-10042",
  "customer": {"email": "buyer@ovion.tech", "name": "Buyer Demo"},
  "order": {},
  "product": {},
  "cart": {},
  "ticket": {},
  "conversation": {},
  "meta": {}
}

7) Webhooks And Signing

Workspace webhooks should include signed headers so receiving systems can verify authenticity.

X-Aibot-Event
X-Aibot-Delivery
X-Aibot-Timestamp
X-Aibot-Signature

Receivers should verify timestamp freshness, compute HMAC with the signing secret, and store delivery IDs when idempotency matters.

8) Production Deployment Notes

APP_ENV=production
APP_DEBUG=false
QUEUE_CONNECTION=database
LOG_LEVEL=warning

Before upload or customer release, run php artisan test and scripts\production-smoke.ps1. The smoke report should show no PHP notices, warnings, undefined variables, undefined array keys, stack traces, or HTTP 500 responses.