gateway/modules/features/commcoach/CONCEPT.md

CommCoach – Communication Coach for Leaders

Product Goal

An AI coaching agent for executives that:

• Captures topics, concerns, and questions
• Asks active diagnostic follow-up questions
• Builds a continuable context per topic (Dossier)
• Conducts daily training conversations
• Makes progress visible (Gamification)
• Supports voice natively (STT/TTS, voice selection)

Architecture

Layers

Transport (REST/SSE)  →  routeFeatureCommcoach.py
Orchestration         →  serviceCommcoach.py
AI Pipeline           →  serviceCommcoachAi.py
Scheduler             →  serviceCommcoachScheduler.py
Domain / Storage      →  interfaceFeatureCommcoach.py
Data Models           →  datamodelCommcoach.py
Feature Registration  →  mainCommcoach.py

Reuse from Existing Codebase

Component	Source	Usage
Feature Plug&Play	registry.py	Auto-discovery via routeFeature*.py
RequestContext + RBAC	authentication.py, interfaceRbac.py	Auth + ownership
DatabaseConnector	connectorDbPostgre.py	New DB poweron_commcoach
VoiceObjects (STT/TTS)	interfaceVoiceObjects.py	Voice pipeline
MessagingInterface	interfaceMessaging.py	Email summaries
SSE Pattern	chatbot routeFeatureChatbot.py	Chat streaming
PDF Renderer	rendererPdf.py	Dossier export (Iteration 2)
EventManagement	eventManagement.py	Scheduled reminders

Domain Model

Entities

User (1) ──── owns ──── (N) CoachingContext
                              │
CoachingContext (1) ────── (N) CoachingSession
                              │
CoachingSession (1) ───── (N) CoachingMessage
                              │
CoachingContext (1) ────── (N) CoachingTask
CoachingContext (1) ────── (N) CoachingScore
User (1) ──────────────── (1) CoachingUserProfile

Status Models

CoachingContext:  active → paused → active | archived → active | completed
CoachingSession:  active → completed | cancelled
CoachingTask:     open → in_progress → done | skipped

API Design

PREFIX: /api/commcoach/{instanceId}

# Contexts (Dossier)
GET    /contexts
POST   /contexts
GET    /contexts/{contextId}
PUT    /contexts/{contextId}
DELETE /contexts/{contextId}
POST   /contexts/{contextId}/archive
POST   /contexts/{contextId}/activate

# Sessions
GET    /contexts/{contextId}/sessions
POST   /contexts/{contextId}/sessions/start
GET    /sessions/{sessionId}
POST   /sessions/{sessionId}/complete
POST   /sessions/{sessionId}/cancel

# Streaming Chat
POST   /sessions/{sessionId}/message/stream
POST   /sessions/{sessionId}/audio/stream
GET    /sessions/{sessionId}/stream

# Tasks
GET    /contexts/{contextId}/tasks
POST   /contexts/{contextId}/tasks
PUT    /tasks/{taskId}
PUT    /tasks/{taskId}/status
DELETE /tasks/{taskId}

# Dashboard
GET    /dashboard

# User Profile
GET    /profile
PUT    /profile

# Voice
GET    /voice/languages
GET    /voice/voices
POST   /voice/tts

SSE Event Types

• message – Complete message
• messageChunk – Streaming token
• sessionState – Status update
• taskCreated – New task from coach
• insightGenerated – New insight
• scoreUpdate – Score change
• status – UI status label
• complete – Stream ended
• error – Error
• ping – Keepalive

RBAC Model

Ownership Rules (Critical)

• Strict MY-only: User sees only own contexts/sessions/messages/tasks/scores
• SysAdmin: Only technical monitoring, NO content access
• No admin override on userId filter

Template Roles

• commcoach-user: DATA=MY on all entities, UI=ALL, RESOURCE=ALL
• commcoach-admin: DATA=MY (intentionally not ALL), UI=ALL, RESOURCE=ALL

Audit Events

• commcoach.context.created/archived
• commcoach.session.started/completed
• commcoach.export.requested

Iterations

Iteration 1 (MVP)

• Context management (create, switch, archive)
• Chat + SSE streaming
• STT/TTS with language/voice selection
• Coaching session with active diagnostic questions
• Auto session protocol
• Tasks/Checklist per context
• Session summary via email
• RBAC + strict ownership
• Basic dashboard: continuity, competence score, goal progress
• Long-session compression: ab 25 Nachrichten wird der aeltere Verlauf per AI zusammengefasst, letzte 15 Nachrichten bleiben vollstaendig (Teamsbot-Pattern)
• Context Memory (Phasen 1-7): previousSessionSummaries im Chat, keyTopics bei completeSession, Intent-Erkennung (summarize_all, recall_session, recall_topic), Datums-Lookup, Topic-Suche, Rolling Overview, RAG-Platzhalter

Iteration 2

• Roleplay personas (critical CFO, difficult employee, etc.)
• Document upload + context binding
• Exports (Markdown/PDF)
• Extended gamification (streaks, levels, badges)
• Better scoring/insights

Database

• Database name: poweron_commcoach
• Tables auto-created from Pydantic models via DatabaseConnector

Frontend

Views

• CommcoachDashboardView – KPIs, streaks, quick start
• CommcoachCoachingView – Chat UI with voice + context tabs
• CommcoachDossierView – Dossier: timeline, tasks, scores
• CommcoachSettingsView – Voice, reminder, profile settings

UX

• Multiple active contexts as quick-switch tabs/chips
• "Daily Coach" entry point prominent
• Voice first, always with text fallback
• Dossier view: timeline, learnings, tasks, next exercise