# 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