Status: ✅ Complete Version: 1.0 Last Updated: December 2025 Author: Engineering Team
1. Overview#
1.1 Summary#
The Persona Chat System enables users to have text and voice conversations with AI-powered teacher personas representing diverse wisdom traditions. Each persona has unique teaching styles, knowledge domains, and personality characteristics.
1.2 Business Context#
- Goal: Provide personalized spiritual guidance from authentic tradition perspectives
- Users: Seekers, students, practitioners across experience levels
- Value: Accessible wisdom teaching without barriers of geography or cost
1.3 Success Metrics#
| Metric | Target |
|---|---|
| Response latency (p50) | < 2 seconds |
| Response latency (p95) | < 4 seconds |
| User satisfaction | > 4.2/5.0 |
| Session completion | > 80% |
| Return rate (7-day) | > 40% |
2. Requirements#
2.1 Functional Requirements#
| ID | Requirement | Priority |
|---|---|---|
| FR-1 | Users can select from available personas | P0 |
| FR-2 | Users can send text messages | P0 |
| FR-3 | Personas respond with streaming text | P0 |
| FR-4 | Personas cite sources when relevant | P0 |
| FR-5 | Users can adjust response depth | P1 |
| FR-6 | Users can adjust response tone | P1 |
| FR-7 | Conversation history is preserved | P0 |
| FR-8 | Users can continue past conversations | P1 |
| FR-9 | Users can request audio responses | P1 |
| FR-10 | Personas maintain session context | P0 |
2.2 Non-Functional Requirements#
| ID | Requirement | Target |
|---|---|---|
| NFR-1 | Availability | 99.9% uptime |
| NFR-2 | Response time | p50 < 2s, p95 < 4s |
| NFR-3 | Concurrent users | 10,000+ |
| NFR-4 | Context window | 128k tokens |
| NFR-5 | Citation accuracy | > 95% |
3. User Stories#
3.1 Core Stories#
US-1: Start Conversation
As a seeker, I want to start a conversation with a Zen Master persona so that I can receive guidance on meditation practice.
Acceptance Criteria:
- User can browse available personas
- User can view persona description and style
- User can start new conversation with selected persona
- First message from persona acknowledges user
US-2: Continue Conversation
As a student, I want to continue a previous conversation so that I can build on our prior discussion.
Acceptance Criteria:
- User can view conversation history
- User can select past conversation
- Persona has context of previous messages
- Conversation picks up naturally
US-3: Get Cited Response
As a researcher, I want responses to include source citations so that I can verify information and explore further.
Acceptance Criteria:
- Citations appear inline or as references
- Citations link to original sources
- Citation confidence scores are shown
- User can enable/disable citation mode
4. Technical Design#
4.1 Architecture#
┌─────────┐ ┌─────────┐ ┌──────────────┐ ┌─────────────┐
│ Client │────>│ BFF │────>│ Conversation │────>│ AI │
│ │<────│ │<────│ Service │<────│ Service │
└─────────┘ └─────────┘ └──────────────┘ └─────────────┘
│ │
▼ ▼
┌──────────────┐ ┌─────────────┐
│ PostgreSQL │ │ RAG │
│ (Messages) │ │ Pipeline │
└──────────────┘ └─────────────┘
4.2 API Endpoints#
Create Chat Turn
POST /v1/chat
Authorization: Bearer <token>
Content-Type: application/json
{
"conversation_id": "uuid", // optional, creates new if omitted
"persona": "zen_master",
"input": {
"text": "How do I quiet my mind during meditation?"
},
"options": {
"cite": true,
"depth": "practical",
"stream": true
}
}
Response (SSE)
event: token
data: {"text":"The"}
event: token
data: {"text":" mind"}
event: citation
data: {"source":"Shunryu Suzuki, Zen Mind Beginner's Mind","confidence":0.92}
event: done
data: {"message_id":"uuid","latency_ms":1834}
4.3 Data Model#
Conversations Table
conversations (
id UUID PRIMARY KEY,
user_id UUID,
persona_key VARCHAR(50),
created_at TIMESTAMPTZ,
updated_at TIMESTAMPTZ,
metadata JSONB
)
Messages Table
messages (
id UUID PRIMARY KEY,
conversation_id UUID,
role VARCHAR(20),
text_ref TEXT,
citations JSONB,
metrics JSONB,
created_at TIMESTAMPTZ
)
4.4 Persona Configuration#
{
"key": "zen_master",
"title": "Zen Master",
"tradition": "Zen Buddhism",
"style_config": {
"teaching_style": "socratic",
"uses_koans": true,
"directness": 0.8,
"humor": 0.3,
"formality": 0.6
},
"system_prompt": "You are a Zen master...",
"voice_id": "calm_male_1",
"policy_tags": ["buddhist", "meditation"]
}
5. UX/UI Considerations#
5.1 Chat Interface#
- Message bubbles with clear user/assistant distinction
- Typing indicator during streaming
- Citation panel (expandable)
- Persona avatar and name visible
- Quick action buttons ("Explain more", "Simpler please")
- Depth/tone sliders
5.2 Persona Selection#
- Grid/list view of personas
- Preview cards with tradition and style
- Search and filter by tradition
- "Try conversation" sample
6. Security Considerations#
6.1 Content Safety#
- All responses pass through moderation service
- Medical/mental health disclaimers injected when relevant
- Crisis guidance for distress signals
- Cultural sensitivity validation
6.2 Data Privacy#
- Conversation data encrypted at rest
- User can delete conversation history
- PII not stored in logs
- Consent required for voice cloning
7. Testing Strategy#
7.1 Test Types#
| Type | Coverage Target |
|---|---|
| Unit tests | 90% |
| Integration tests | 80% |
| E2E tests | Critical paths |
| Load tests | 10k concurrent |
| Security tests | OWASP Top 10 |
7.2 Acceptance Criteria#
- All personas respond within SLA
- Citations are accurate and verifiable
- Conversations persist across sessions
- Moderation catches unsafe content
- Voice responses sync with text
8. Rollout Plan#
8.1 Feature Flags#
| Flag | Description |
|---|---|
persona_chat_enabled |
Master enable |
persona_chat_citations |
Citation mode |
persona_chat_voice |
Voice responses |
persona_chat_depth_controls |
Depth/tone sliders |
8.2 Phased Rollout#
- Alpha: Internal team only
- Beta: 5% of users, Zen/Stoic personas only
- GA Phase 1: 25% of users, all MVP personas
- GA Phase 2: 100% of users