Case 05: DNA Clotilde – AI-Powered Sales Enablement

• SSE streaming chat with response cancellation
• SDR/Closer mode, tone, formality, and objective configurable
• Automatic suggestions by objective (action chips)
• Quick templates per objective and mode
• Image and text attachments to enrich context
• Audio transcription via URL or upload (AssemblyAI + Vercel Blob)
• Embeddable widget via query param ?widget=commercial (client-simulated responses)
• Per-message feedback (👍/👎) and session export
• UI with design system tokens and microinteractions (GSAP)

• Overview
• Architecture
• Core Flows
• Technical Stack
• Repository Structure
• Running Locally
• Environment Configuration
• API
• Deploy
• Observability and Logs
• Security and Privacy
• Limits and Quotas
• Troubleshooting
• Tests and Quality
• Maintenance
• Internal References

The project delivers a chat experience focused on commercial activities (SDR/Closer), with LLM-generated answers via SSE streaming. The frontend maintains local conversation state and provides operational features (templates, suggestions, export, transcription), while the backend concentrates streaming and integrations with OpenAI and AssemblyAI.

The monorepo also includes serverless functions for Vercel deployment (frontend/api), enabling operation without the Express backend in production when desired.

1) SSE streaming chat

• Endpoint: POST /chat/stream (backend) or POST /api/chat/stream (Vercel)
• SSE format with events open, ping, error, suggestions, and end
• Frontend consumes the stream, aggregates chunks, and reports UX metrics (time to first token and total)

Example payload:

{
  "message": "I need an outreach script",
  "mode": "SDR",
  "tone": "brief",
  "formality": "informal",
  "objective": "qualify",
  "attachments": [
    { "kind": "text", "content": "Lead context...", "name": "context.txt" },
    { "kind": "image", "content": "data:image/png;base64,..." }
  ]
}

Returned events (example):

event: open

data: {}

data: {"chunk":"Hello!"}

event: suggestions

data: {"suggestions":["Ask about budget", "..." ]}

event: end

data: {}

2) Templates and suggestions

• Predefined templates by mode: GET /templates?mode=SDR|Closer
• Automatic suggestions emitted by the backend when a response is valid

3) Audio transcription

URL flow:

1. Frontend calls POST /transcriptions (backend) or POST /api/transcriptions (Vercel) with audio_url
2. Backend creates a transcription on AssemblyAI and returns { id, status }
3. Frontend polls GET /transcriptions/:id or GET /api/transcriptions/:id

File flow:

1. Frontend uploads to Vercel Blob via POST /api/blob/upload
2. Receives a public blob URL
3. Creates transcription via POST /api/transcriptions with audio_url pointing to the blob

4) Analysis with citations (serverless)

• Endpoint: POST /api/analyze
• Objective: transcript analysis with fixed structure and citations (T# for transcript, W# for Web)
• Optional Web support via Tavily (enableWeb=true)
• Truncates transcripts at 20k characters and applies chunking (800 with 120 overlap)

Minimum payload:

{
  "query": "Summary with risks and next steps",
  "transcriptText": "..."
}

5) LLM provider

LLM_PROVIDER controls the engine used in the Express backend:

• openai_chat (default): real streaming via Chat Completions, with model fallback when streaming is restricted.
• openai_assistants: uses Assistants API v2 with ephemeral threads and polling; streaming is simulated by chunking the final response.

Prerequisites:

• Node.js 20.x (.nvmrc)
• npm 8+

Steps:

1. Install dependencies at the repo root

npm install

1. Start frontend and backend in dev mode

npm run dev

Default ports:

• Backend: http://localhost:3001
• Frontend: http://localhost:5174

Build and run backend:

npm run build
npm run start

Express Backend (backend/src/config.js)

Frontend (Vite)

Vercel Functions (frontend/api)

Notes:

• In production, the frontend ignores VITE_BACKEND_URL when pointing to localhost and uses /api (Vercel).
• Do not commit .env.

Express Backend

GET /health

• Returns { status: "ok" }.

POST /chat/stream (SSE)

• Accepts: { message, mode, tone, formality, objective, attachments }
• Returns text/event-stream, heartbeat every 15s.

GET /templates

• Query: ?mode=SDR|Closer
• Returns predefined templates by objective.

POST /feedback

• Body: { rating: "up"|"down", reason?: string }
• Logs feedback only.

GET /diagnostics/llm

• Streaming diagnostics for preferred model.
• Returns canStream, recommendation, and details.

POST /transcriptions

• Body: { audio_url, speaker_labels?, language_code? }
• Returns { id, status }.

GET /transcriptions/:id

• Returns transcription status and content.

POST /blob/upload

• Token proxy for Vercel Blob upload.

POST /transcriptions/upload

• Proxy for direct AssemblyAI upload (legacy).

Vercel Functions

POST /api/chat/stream

• Serverless SSE stream.
• Implements dedicated rate limit and timeout.

POST /api/transcriptions

GET /api/transcriptions/:id

POST /api/blob/upload

• File upload to Vercel Blob (token issuance).

POST /api/transcriptions/upload

• Deprecated endpoint (returns 410).

POST /api/analyze

• Structured analysis with T# and W# citations.

Option 1: Monorepo with Express backend

• Run npm run build at the root.
• Run npm run start in the backend.
• Publish the Vite frontend output (frontend/dist).

Option 2: Vercel (serverless)

• Functions in frontend/api replace the Express backend.
• Frontend uses /api automatically in production.
• Configure environment variables in Vercel per the table above.

• Express backend uses pino and pino-http with structured logs.
• Serverless functions use JSON logs and requestId for tracing.
• Frontend logs UX metrics without PII (logUX).

• No authentication and no data persistence in v1.
• In-memory rate limit per IP (5 min window).
• CSP configured in vercel.json to limit origins.
• UI renders text only, no arbitrary HTML, preventing XSS.
• Avoid sending PII or secrets in chat.

• Chat input: 2000 characters.
• Text attachment: up to 1 MB.
• Image attachment: up to 4 MB.
• Transcription upload: preventive limit VITE_MAX_UPLOAD_MB (default 500 MB).
• Rate limit: 60 req/5min (general) and 30 req/5min (chat).

• MISSING_API_KEY: configure OPENAI_API_KEY or ASSEMBLYAI_API_KEY.
• Streaming not allowed: use OPENAI_MODEL_FALLBACK or adjust the model.
• TIMEOUT: increase CHAT_STREAM_TIMEOUT_MS or reduce OPENAI_MAX_TOKENS.
• Transcription errors: ensure the audio URL is public and accessible.

Backend:

npm run test -w backend
npm run lint -w backend

Frontend:

npm run test -w frontend
npm run e2e -w frontend
npm run lint -w frontend
npm run lint:styles

• npm audit and npm audit fix for security.
• Update dependencies periodically.
• Review tokens and guidelines in docs/design-system.md.

• Design system: docs/design-system.md
• Plan and requirements: prd.md, plan.md