convoai 1.5.3 → 1.6.1

package/dist/src/starters/web/server/index.js

@@ -0,0 +1,85 @@
+// ConvoAI Starter — Express Server
+// Serves frontend static files + Agora RTC SDK + API routes.
+import 'dotenv/config';
+import express from 'express';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import sessionRouter from './routes/session.js';
+import tokenRouter from './routes/token.js';
+import callbackRouter from './routes/callback.js';
+import knowledgeRouter from './routes/knowledge.js';
+import { getHistory } from './convoai-api.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+const app = express();
+const PORT = parseInt(process.env.PORT || '3000', 10);
+// ─── Middleware ─────────────────────────────────────────────────────────────
+app.use(express.json());
+// ─── Agora RTC SDK from npm ────────────────────────────────────────────────
+let sdkCache = null;
+app.get('/agora-sdk.js', (_req, res) => {
+    if (!sdkCache) {
+        const sdkPath = require.resolve('agora-rtc-sdk-ng/AgoraRTC_N-production.js');
+        sdkCache = readFileSync(sdkPath);
+    }
+    res.set({
+        'Content-Type': 'application/javascript; charset=utf-8',
+        'Content-Length': String(sdkCache.length),
+        'Cache-Control': 'public, max-age=86400',
+    });
+    res.send(sdkCache);
+});
+// ─── API Routes ────────────────────────────────────────────────────────────
+app.use(sessionRouter);
+app.use(tokenRouter);
+app.use(callbackRouter);
+app.use(knowledgeRouter);
+app.get('/health', (_req, res) => {
+    res.json({ status: 'ok' });
+});
+// ─── History Proxy ─────────────────────────────────────────────────────────
+app.get('/history', async (req, res) => {
+    const agentId = req.query.agentId;
+    if (!agentId) {
+        res.status(400).json({ error: 'Missing agentId query parameter' });
+        return;
+    }
+    try {
+        const appId = process.env.AGORA_APP_ID;
+        const customerId = process.env.AGORA_CUSTOMER_ID;
+        const customerSecret = process.env.AGORA_CUSTOMER_SECRET;
+        const region = process.env.AGORA_REGION || 'global';
+        const history = await getHistory(appId, agentId, customerId, customerSecret, region);
+        res.json({ history });
+    }
+    catch {
+        res.json({ history: [] });
+    }
+});
+// ─── Frontend Static Files ─────────────────────────────────────────────────
+const frontendDir = join(__dirname, '..', 'frontend');
+app.use(express.static(frontendDir));
+// ─── Start Server ──────────────────────────────────────────────────────────
+app.listen(PORT, () => {
+    console.log('');
+    console.log(`  ConvoAI Starter Server running at:`);
+    console.log(`  -> http://localhost:${PORT}`);
+    console.log('');
+    console.log(`  API routes:`);
+    console.log(`    POST /session/start   Start voice conversation`);
+    console.log(`    POST /session/stop    Stop conversation`);
+    console.log(`    GET  /token           Generate RTC token`);
+    console.log(`    GET  /health          Health check`);
+    console.log('');
+    const required = ['AGORA_APP_ID', 'AGORA_APP_CERTIFICATE', 'AGORA_CUSTOMER_ID', 'AGORA_CUSTOMER_SECRET'];
+    const missing = required.filter(k => !process.env[k]);
+    if (missing.length > 0) {
+        console.log(`  ⚠ Missing credentials in .env: ${missing.join(', ')}`);
+        console.log(`  Run "convoai quickstart" to configure, or edit .env manually.`);
+        console.log('');
+    }
+});
+//# sourceMappingURL=index.js.map

package/dist/src/starters/web/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/starters/web/server/index.ts"],"names":[],"mappings":"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"}

package/dist/src/starters/web/server/routes/callback.d.ts

@@ -0,0 +1,2 @@
+declare const router: any;
+export default router;

package/dist/src/starters/web/server/routes/callback.js

@@ -0,0 +1,10 @@
+// Webhook endpoint for ConvoAI Engine callbacks.
+// Customize: add your webhook handling logic here.
+import { Router } from 'express';
+const router = Router();
+router.post('/callback', (req, res) => {
+    console.log('[callback] Received webhook:', JSON.stringify(req.body, null, 2));
+    res.json({ received: true });
+});
+export default router;
+//# sourceMappingURL=callback.js.map

package/dist/src/starters/web/server/routes/callback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback.js","sourceRoot":"","sources":["../../../../../../src/starters/web/server/routes/callback.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,mDAAmD;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;AAExB,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACpC,OAAO,CAAC,GAAG,CAAC,8BAA8B,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/E,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/src/starters/web/server/routes/knowledge.d.ts

@@ -0,0 +1,2 @@
+declare const router: any;
+export default router;

package/dist/src/starters/web/server/routes/knowledge.js

@@ -0,0 +1,15 @@
+// Knowledge base query endpoint.
+// Customize: connect your knowledge base, RAG pipeline, or vector DB here.
+import { Router } from 'express';
+const router = Router();
+router.post('/knowledge', (req, res) => {
+    const { query } = req.body || {};
+    console.log('[knowledge] Query:', query);
+    // Customize: replace with your knowledge base integration
+    res.json({
+        results: [],
+        message: 'Knowledge base not configured. Edit server/routes/knowledge.ts to connect yours.',
+    });
+});
+export default router;
+//# sourceMappingURL=knowledge.js.map

package/dist/src/starters/web/server/routes/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../../../../../src/starters/web/server/routes/knowledge.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,2EAA2E;AAE3E,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;AAExB,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACrC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;IAEzC,0DAA0D;IAC1D,GAAG,CAAC,IAAI,CAAC;QACP,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,kFAAkF;KAC5F,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/src/starters/web/server/routes/session.d.ts

@@ -0,0 +1,2 @@
+declare const router: any;
+export default router;

package/dist/src/starters/web/server/routes/session.js

@@ -0,0 +1,82 @@
+import { Router } from 'express';
+import { startAgent, stopAgent } from '../convoai-api.js';
+const router = Router();
+// In-memory session store (single session for simplicity)
+// Customize: replace with database or Redis for production
+let currentSession = null;
+router.post('/session/start', async (req, res) => {
+    try {
+        if (currentSession) {
+            res.status(409).json({ error: 'Session already active. Stop it first.' });
+            return;
+        }
+        const appId = process.env.AGORA_APP_ID;
+        const appCertificate = process.env.AGORA_APP_CERTIFICATE;
+        const customerId = process.env.AGORA_CUSTOMER_ID;
+        const customerSecret = process.env.AGORA_CUSTOMER_SECRET;
+        const region = process.env.AGORA_REGION || 'global';
+        const channel = `session-${Date.now().toString(36)}`;
+        const clientUid = Math.floor(Math.random() * 90000) + 10000;
+        const config = {
+            appId,
+            appCertificate,
+            customerId,
+            customerSecret,
+            region,
+            channel,
+            clientUid,
+            llm: {
+                vendor: process.env.LLM_VENDOR,
+                model: process.env.LLM_MODEL,
+                apiKey: process.env.LLM_API_KEY,
+                url: process.env.LLM_URL,
+                style: process.env.LLM_STYLE,
+            },
+            tts: {
+                vendor: process.env.TTS_VENDOR,
+                apiKey: process.env.TTS_API_KEY,
+            },
+            asr: {
+                vendor: process.env.ASR_VENDOR,
+                language: process.env.ASR_LANGUAGE,
+            },
+        };
+        const result = await startAgent(config);
+        currentSession = { agentId: result.agentId, channel: result.channel };
+        res.json({
+            appId: result.appId,
+            channel: result.channel,
+            token: result.token,
+            uid: result.uid,
+            agentId: result.agentId,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        console.error('[session/start]', message);
+        res.status(500).json({ error: message });
+    }
+});
+router.post('/session/stop', async (req, res) => {
+    try {
+        if (!currentSession) {
+            res.status(404).json({ error: 'No active session' });
+            return;
+        }
+        const appId = process.env.AGORA_APP_ID;
+        const customerId = process.env.AGORA_CUSTOMER_ID;
+        const customerSecret = process.env.AGORA_CUSTOMER_SECRET;
+        const region = process.env.AGORA_REGION || 'global';
+        await stopAgent(appId, currentSession.agentId, customerId, customerSecret, region);
+        currentSession = null;
+        res.json({ status: 'stopped' });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        console.error('[session/stop]', message);
+        currentSession = null;
+        res.status(500).json({ error: message });
+    }
+});
+export default router;
+//# sourceMappingURL=session.js.map

package/dist/src/starters/web/server/routes/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../../../../src/starters/web/server/routes/session.ts"],"names":[],"mappings":"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"}

package/dist/src/starters/web/server/routes/token.d.ts

@@ -0,0 +1,2 @@
+declare const router: any;
+export default router;

package/dist/src/starters/web/server/routes/token.js

@@ -0,0 +1,19 @@
+import { Router } from 'express';
+import { generateToken } from '../convoai-api.js';
+const router = Router();
+router.get('/token', (req, res) => {
+    try {
+        const appId = process.env.AGORA_APP_ID;
+        const appCertificate = process.env.AGORA_APP_CERTIFICATE;
+        const channel = req.query.channel || `ch-${Date.now().toString(36)}`;
+        const uid = parseInt(req.query.uid, 10) || 0;
+        const token = generateToken(appId, appCertificate, channel, uid);
+        res.json({ token, channel, uid });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        res.status(500).json({ error: message });
+    }
+});
+export default router;
+//# sourceMappingURL=token.js.map

package/dist/src/starters/web/server/routes/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../../../../../src/starters/web/server/routes/token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;AAExB,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IAChC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAa,CAAC;QACxC,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAsB,CAAC;QAC1D,MAAM,OAAO,GAAI,GAAG,CAAC,KAAK,CAAC,OAAkB,IAAI,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACjF,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,GAAa,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QAEvD,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QAEjE,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/src/web/serve.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * Returns an HTTP request handler that serves:
+ *  - `/agora-sdk.js` → Agora RTC SDK from node_modules
+ *  - Everything else  → the provided HTML string
+ */
+export declare function createWebHandler(html: string): (req: IncomingMessage, res: ServerResponse) => void;

package/dist/src/web/serve.js

@@ -0,0 +1,42 @@
+/**
+ * Shared HTTP handler that serves HTML pages + the Agora RTC SDK from npm.
+ * Using the npm package (agora-rtc-sdk-ng) instead of CDN ensures each
+ * `npm install convoai` counts as an npm download for the SDK.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+let _sdkCache = null;
+function getSdkContent() {
+    if (!_sdkCache) {
+        // Resolve the package main entry (exports "." → AgoraRTC_N-production.js)
+        // Using the subpath directly would throw ERR_PACKAGE_PATH_NOT_EXPORTED
+        const sdkPath = require.resolve('agora-rtc-sdk-ng');
+        _sdkCache = readFileSync(sdkPath);
+    }
+    return _sdkCache;
+}
+/**
+ * Returns an HTTP request handler that serves:
+ *  - `/agora-sdk.js` → Agora RTC SDK from node_modules
+ *  - Everything else  → the provided HTML string
+ */
+export function createWebHandler(html) {
+    return (req, res) => {
+        const pathname = (req.url || '/').split('?')[0];
+        if (pathname === '/agora-sdk.js') {
+            const sdk = getSdkContent();
+            res.writeHead(200, {
+                'Content-Type': 'application/javascript; charset=utf-8',
+                'Content-Length': sdk.length,
+                'Cache-Control': 'public, max-age=86400',
+            });
+            res.end(sdk);
+        }
+        else {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(html);
+        }
+    };
+}
+//# sourceMappingURL=serve.js.map

package/dist/src/web/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../../src/web/serve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,IAAI,SAAS,GAAkB,IAAI,CAAC;AAEpC,SAAS,aAAa;IACpB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,0EAA0E;QAC1E,uEAAuE;QACvE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QACpD,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAClB,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,eAAe,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;YAC5B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;gBACjB,cAAc,EAAE,uCAAuC;gBACvD,gBAAgB,EAAE,GAAG,CAAC,MAAM;gBAC5B,eAAe,EAAE,uBAAuB;aACzC,CAAC,CAAC;YACH,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,0BAA0B,EAAE,CAAC,CAAC;YACnE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convoai",
-  "version": "1.5.3",
+  "version": "1.6.1",
   "description": "CLI for Agora ConvoAI Engine — start, manage, and monitor conversational AI agents",
   "type": "module",
   "bin": {
@@ -37,11 +37,13 @@
     "dist",
     "bin",
     "src/web",
+    "src/starters",
     "README.md",
     "LICENSE"
   ],
   "license": "MIT",
   "dependencies": {
+    "agora-rtc-sdk-ng": "^4.24.3",
     "agora-token": "^2.0.5",
     "axios": "^1.7.0",
     "chalk": "^5.3.0",

package/src/starters/web/.env.example

@@ -0,0 +1,28 @@
+# Agora Credentials (from https://console.agora.io)
+AGORA_APP_ID=
+AGORA_APP_CERTIFICATE=
+AGORA_CUSTOMER_ID=
+AGORA_CUSTOMER_SECRET=
+
+# Region: "global" or "cn"
+AGORA_REGION=global
+
+# LLM Configuration
+LLM_VENDOR=openai
+LLM_MODEL=gpt-4o-mini
+LLM_API_KEY=
+LLM_URL=
+LLM_STYLE=openai
+
+# TTS Configuration
+TTS_VENDOR=microsoft
+# TTS_PARAMS is a JSON string with all provider-specific params
+# Examples:
+#   Microsoft: {"key":"...","region":"eastus","voice_name":"en-US-AndrewMultilingualNeural"}
+#   MiniMax:   {"key":"...","group_id":"...","model":"speech-02-turbo","voice_setting":{"voice_id":"..."},"url":"wss://api.minimaxi.com/ws/v1/t2a_v2"}
+#   ElevenLabs: {"key":"...","base_url":"wss://api.elevenlabs.io/v1","model_id":"eleven_flash_v2_5","voice_id":"pNInz6obpgDQGcFmaJgB"}
+TTS_PARAMS=
+
+# ASR Configuration
+ASR_VENDOR=ares
+ASR_LANGUAGE=en-US

package/src/starters/web/README.md

@@ -0,0 +1,81 @@
+# ConvoAI Web Starter
+
+A three-layer starter project for building voice AI applications with Agora ConvoAI Engine.
+
+## Quick Start
+
+```bash
+npm install
+convoai dev          # or: npm run dev
+```
+
+Open http://localhost:3000 and click **Start Conversation**.
+
+## Project Structure
+
+```
+frontend/            <- Your UI (HTML / JS / CSS — no build step)
+server/              <- Your backend (Express + TypeScript)
+python-server/       <- Alternative Python backend (FastAPI)
+connectors/          <- Future: telephony, text, IoT extensions
+```
+
+## How to Customize
+
+### Change the UI
+Edit files in `frontend/`:
+- `index.html` — page structure
+- `style.css` — colors, layout, theme
+- `app.js` — interaction logic, Agora RTC handling
+
+### Add business logic
+Edit files in `server/routes/`:
+- `session.ts` — session start/stop (add auth, rate limiting, logging)
+- `callback.ts` — handle ConvoAI webhooks
+- `knowledge.ts` — connect your knowledge base or RAG pipeline
+
+### Add authentication
+Edit `server/index.ts` — add Express middleware before the API routes.
+
+### Switch to Python
+See `python-server/README.md`. Same API routes, same frontend.
+
+## Architecture
+
+```
+[Your Frontend]  -->  [Your Server]  -->  [ConvoAI Engine]
+     HTML/JS          Express/FastAPI      Agora Cloud
+     Agora RTC SDK    Token generation     ASR + LLM + TTS
+     Voice capture    Business logic       Voice AI pipeline
+```
+
+Future connectors plug in at the same server layer:
+```
+[Phone / SIP]    -->  [Your Server]  -->  [ConvoAI Engine]
+[IoT Device]     -->  [Your Server]  -->  [ConvoAI Engine]
+[IM / Chat App]  -->  [Your Server]  -->  [ConvoAI Engine]
+```
+
+## From Local to Production
+
+1. **Local** — `npm run dev` (you are here)
+2. **Deploy server** — push `server/` to your cloud (Railway, Render, AWS, etc.)
+3. **Deploy frontend** — push `frontend/` to CDN or same server
+4. **Update .env** — swap local credentials for production ones
+
+No code changes needed. Same architecture scales from laptop to production.
+
+## Environment Variables
+
+See `.env.example` for the full list. Key variables:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| AGORA_APP_ID | Yes | From Agora Console |
+| AGORA_APP_CERTIFICATE | Yes | From project settings |
+| AGORA_CUSTOMER_ID | Yes | REST API credentials |
+| AGORA_CUSTOMER_SECRET | Yes | REST API credentials |
+| LLM_VENDOR | Yes | LLM provider (openai, anthropic, etc.) |
+| LLM_API_KEY | Yes | LLM API key |
+| TTS_VENDOR | Yes | TTS provider (microsoft, elevenlabs, etc.) |
+| TTS_API_KEY | Yes | TTS API key |

package/src/starters/web/connectors/README.md

@@ -0,0 +1,35 @@
+# ConvoAI Connectors
+
+This directory is reserved for future communication connectors.
+
+## Architecture
+
+ConvoAI uses a three-layer architecture:
+
+```
+[Connector]  -->  [Customer Server]  -->  [ConvoAI Engine]
+```
+
+New communication capabilities extend through the Connector layer.
+The Customer Server and ConvoAI Engine remain the same.
+
+**Web is the first connector** — implemented in `frontend/`.
+
+## Planned Connectors
+
+### Telephony / SIP (Phase 2)
+Inbound/outbound phone calls via SIP. Connector handles call signaling; server handles business logic.
+
+### Text / IM (Phase 3)
+Chat platforms (Slack, WhatsApp, web chat widgets). Connector handles message transport.
+
+### Device / Edge (Phase 3)
+IoT devices, smart speakers, embedded systems. Connector handles device communication.
+
+## Design Principle
+
+Each connector only handles communication transport.
+Business logic stays in the Customer Server.
+AI capabilities stay in ConvoAI Engine.
+
+Adding a new connector never requires rewriting your server or AI config.