TrueServe Framework Developer Handbook¶

Status: Current | Last reviewed: 2026-10-20

This handbook is the canonical guide to working on TrueServe Framework. Read it in order if you are new. Jump by topic if you are not.

The repo's root README.md introduces the project. The root CLAUDE.md tells AI agents how to behave per environment. This handbook is for humans and agents who need to understand or change the system.

The rendered developer handbook is a MkDocs site using the Material theme through mkdocs.developer.yml. The end-user guide is a separate MkDocs site using the vendored docSkimmer theme through mkdocs.userguide.yml.

Every doc on this page declares a status: Current, Draft, Stale, or Archived. If you find a Stale doc, fix it or move it to _archive/. The rules for writing docs live in STYLE.md.

Reading order for new developers¶

Quick start: clone the repo, run wake-up.sh, hit a service.
Environment modes: identify Vanguard, Sentinel, and customer-cluster workflows.
Repo tour: learn what each top-level directory contains.
Runtime targets: see the three places this code runs.
Voice request lifecycle: follow a phone call through the system.
Universal pipeline builder: learn how agents are configured and executed before you change ai-manager or ai-orchestrator.

For GPT Live voice/backend integration, read OpenAI GPT Live.

For the Takeda Voice Agent, human Copilot, dynamic Salesforce workspace and latency evidence, read Takeda demo.

For the live Salesforce app branding, three-column page and component inventory, read DevSDO Lightning UI audit.

For the hosted PSP app, Genesys outbound welcome calls and SDK event projection, read ClearConnect.

For the unified Behavioral and English Assessments app, read the architecture and interactive diagram, production readiness and operations/validation plan. The English implementation reference covers its detailed contracts. To continue work from the blocked Language Assessment Codex thread, use the Assessments AI handoff.

For switching Agent Studio generation and design to the managed Agents API, read OpenAI authoring.

Sections¶

01: Getting started¶

02: Architecture¶

GECX, MCP and companion forms: interactive architecture, API sequence, ANI and SMS/mobile handoff.
Runtime targets
Voice request lifecycle
Agentforce Voice companion forms: ACG auto demo architecture and Salesforce developer handoff.
Chat request lifecycle
Personal Agent Protocol adoption: draft proposal for assistant access, customer delegation and transactional operations.
Async request lifecycle
Data model overview
Multi-tenancy
Knowledge Management Agents: native RAGFlow preparation, evidence testing and publication.
Analytics Agents: canvas, model/prompt configuration, ingestion, report compilation and operations.
Analytics composition: published component catalogues, tool policies and configurable opening briefings.
Analytics migration validation: source comparisons, migrated demos, visual checks and performance limits.
SIP edge modularization + pluggable voice runtimes (Draft)
Pipecat-native alignment + horizon agents (Draft)
A2UI spec convergence (Draft)
Context-efficiency backlog: audited large/hot files, their split seams, and the tests that assert on source structure — read before proposing a refactor.

03: Services¶

Service catalog: every coded and configured service, grouped by role.
Service tiers: which services a regression makes an incident, and the test/docs bar each tier owes.
Ari Assistant: separate Studio-authenticated OpenMuse browser app and Poppy protocol lab.
Poppy Company gateway: reviewed guest agent endpoints, version pins and runtime delivery.
Voice runtime: ai-orchestrator, ai-manager, agent-host, async-agent, media-proxy, ari-controller
Integrations: Genesys, Webex, Five9, Teams, Amazon Connect, Salesforce SCV, Authentik sync
Frontend: surface-app, code-server, optional legacy crm-dashboard / crm-api
Knowledge & data: conversation-api, catalog-builder, multimodal-service, collab-gateway, optional legacy knowledge-engine
Telephony stack (configured): asterisk, kamailio, janus, rtpengine, coturn
Shared libraries
Ganymede user provisioning: permission-gated Salesforce and Authentik account creation.

Compliance and assurance¶

Implementation guide: enforced profiles, regulated AWS activation, tenant assignment, release gates, evidence, and external acceptance.
Privacy-rights operations
AI governance release controls
GovCloud and FedRAMP High readiness (Planned)
Standards readiness review
Cross-standard control gap register

04: Processes¶

Director — scripted voice, Salesforce and Headless Agent Assist stages, saved component output and MP4 rendering.
Personal assistant Scenes — phone app, IVR, linked browser chat and human Messaging Sessions.
Director Agent Assist stages — console configuration, captured Copilot output, shared audio routing and visual cues.
Scene Agent Assist consoles — Salesforce/Headless reference investigation and design record.
Consumer Cellular native Connect demo — native human-agent assistance, seeded cases and call rehearsal.
Universal pipeline builder (critical)
SIP integrations
Real-time translation
AWS real-time translation and performance comparison
Copilot API
Warm hand-off
Human Supervision — the supervisor copilot loop
Audio ducking
LangGraph construction
Workflow triggers
ai-manager file layout
Unified Studio UI prototype
Studio dashboard integration and backend follow-up
Studio UI rollout in the real app
AI Manager experience alignment — shared UI refinements and prototype verification.
Multi-agent demos
Allianz annuity demonstration: installed beneficiary Copilot, producer GPT Live agent, human review, branding and test commands
Allianz demo validation: latest passing voice scenarios, Copilot/supervisor latency and test limits
Allianz producer workspace — native illustration form, catalogue guidance, measured pace and call controls.
Allianz self-service v2 — agent 4873, the 4463 speech architecture, verified policy tools and customer cards.
Amazon GREF facilities — voice self-service, source-backed Salesforce handoff and reviewed facilities follow-up.
Allianz producer Copilot experience: twelve-screen design review, Clear Connect native-center pattern, existing DevSDO sidebar/modal reuse and visual acceptance criteria
Conversational authoring research spike (draft)
Conversational authoring implementation research: four agent types, security requirements, runtime selection, tool placeholders, multimodal contracts, and generated evaluations (draft)
Knowledge Management Agent plan: editable preparation, transcript-derived questions and Call Drivers reuse, topic/terminology modeling, policy evidence graphs, evaluation and index health (draft)
Design prototype mode
Designer repository workflow — independent history and advisory commit-time impact tracking.
Phone emulator
External Studio management API, MCP, and A2A
Secret storage
A2UI rendering
Human-controlled customer components
Presence and collaboration
Customer Authentication
Payments (PCI)
Prompt auto-injections
Copilots (Agent Assist)
Record-backed Agent Assist profiles
Capability packs
Cost estimation and usage attribution
Layered PII/PHI protection (design)
Runtime profiles (design)
Procedure supervision + SLM extraction

05: Deployment¶

06: Schema¶

Schema guide — what columns mean + which services use them (data dictionary)
Overview
Tables
Rename map
SQL functions
Migration conventions
Cleanup proposals

07: Infrastructure¶

API¶

SDK¶

Overview
Embedding surface-app
postMessage protocol
Host capabilities
CRM embed components: the Salesforce + ServiceNow wrappers, and why surface-app is the single embed UI
Embedding the demo phone
Reference: auto-generated from lib/embed/bridge.ts

Compliance¶

Customer Authentication control mapping: FFIEC / HIPAA / NIST 800-63B, claim-by-claim with code + test references
Standards readiness review: SOC 2, HIPAA, GDPR, PCI DSS, FedRAMP High, CCPA, CSA STAR, ISO 27001, and ISO 42001 readiness
Cross-standard control gap register: prioritized remediation and closure evidence for regulated deployment profiles
Compliance implementation plan: target architecture, rollout, verification, and definition of done
Compliance implementation backlog: dependency-ordered tasks for future implementation

Archived material¶

_archive/2026-05-pre-overhaul/: the previous docs/ tree, snapshotted on 2026-05-28. Use it for historical context; do not link to it from current docs.
_archive/ (root): older designs that were not implemented. Read them for background; treat them as decisions, not plans.

Where things are not in this handbook¶

Some content lives outside docs/ because it changes with code:

Per-app READMEs (apps/*/README.md): runtime details, ports, and integrations for each service.
Per-app agent guides (apps/*/CLAUDE.md): the invariants an agent must know before editing that service — the mistakes that produce silent failures, and why. Claude Code loads a CLAUDE.md automatically when the work is under its directory, so this detail costs context only in the sessions that need it. The root CLAUDE.md keeps a one-line index of every entry plus the cross-cutting invariants. Same convention as deployment/CLAUDE.md and .devcontainer/CLAUDE.md, applied per service.
Per-chart READMEs (charts/*/README.md): Helm chart values and conventions.
Slash commands (.claude/commands/*.md): agent-invoked recipes, such as /local-status.
Local dev cheatsheet (.devcontainer/CLAUDE.md): daily commands inside the devcontainer.

This handbook links to those when you need them. It does not duplicate them.

A CLAUDE.md bullet and a handbook page are not interchangeable. The bullet is the compressed warning an agent reads before touching the code; the page is the explanation. When a bullet carries incident detail the page does not, the page is incomplete — fix the page rather than trimming the bullet.