Researched: 2026-03-24 Domain: AI coaching simulation, real-time streaming chat, multi-dimensional scoring, admin CRUD Confidence: HIGH

Phase 2 transforms the foundation from Phase 1 into a working AI coaching platform. It requires five major workstreams: (1) database models and Alembic migrations for HCP profiles, scenarios, coaching sessions, messages, and scores; (2) backend API routers and services for CRUD operations, streaming chat via SSE, and post-session scoring; (3) admin UI pages for managing HCP profiles and scenarios; (4) user-facing coaching UI with a 3-column layout, real-time chat, key message tracking, and coaching hints; (5) post-session scoring feedback page with radar chart visualization.

The existing codebase provides strong foundations: BaseCoachingAdapter with CoachEvent streaming, ServiceRegistry for adapter management, auth/role system, 17 shadcn/ui components, i18n setup, and Tailwind v4 design tokens including scoring semantic colors. The primary technical challenges are SSE streaming through the Vite proxy, system prompt engineering for HCP personality fidelity, and the linked scoring weight sliders that must total 100%.

Primary recommendation: Use SSE (Server-Sent Events) via sse-starlette for streaming HCP responses (simpler than WebSocket for text-only, one-directional streaming). Add recharts for the radar chart on the scoring page. Extend BaseCoachingAdapter and CoachEvent types for conversation context and key message tracking. Maximize parallelization with 4 independent workstreams: backend models/API, admin UI, coaching UI, and scoring engine/UI.

<user_constraints>

• D-01: AI HCP responds with streaming word-by-word via SSE/WebSocket -- extends existing CoachEvent streaming pattern from BaseCoachingAdapter
• D-02: Coaching hints use hybrid approach -- static scenario hints loaded at session start + contextual hints triggered at key conversation moments (e.g., when MR misses an objection handling opportunity). Separate AI call for milestone triggers.
• D-03: Key message tracking via AI auto-detection -- after each MR message, AI evaluates whether any key messages were delivered, checklist updates automatically in real-time
• D-04: Scoring is post-session only -- single AI analysis of full transcript after "End Session". No real-time score preview during conversation.
• D-05: Full feedback report per Figma spec (06-scoring-feedback.md) -- radar chart comparing current vs previous session, dimension score bars (green>80, orange 60-80, red<60), detailed strengths/weaknesses with conversation quotes, actionable suggestions per dimension
• D-06: Session end via manual button + HCP-initiated -- MR can click "End Session" anytime, AI HCP may also initiate end ("I need to go to my next patient") after key messages are covered or based on session duration. Most realistic simulation.
• D-07: HCP profile editor uses full form layout per Figma spec (09-admin-hcp-scenarios.md) -- left sidebar HCP list + right editor panel with identity fields, personality sliders, knowledge background, and interaction rules
• D-08: Scoring weights use linked sliders totaling 100% -- when one slider increases, others decrease proportionally. 5 dimensions: Key Message Delivery, Objection Handling, Communication Skills, Product Knowledge, Scientific Information
• D-09: Quick "Test Chat" feature for HCP profiles -- admin can open a mini-chat dialog to test HCP personality before assigning to scenarios. Uses same coaching engine.
• D-10: Strict character adherence -- AI strictly stays in character per HCP profile. Personality type, objections, knowledge, and communication style are all enforced in the system prompt.
• D-11: Full session context for conversation memory -- entire conversation history sent with each turn.
• D-12: Realistic mock provider with templates -- pre-scripted responses based on scenario context with personality-appropriate variations and some randomization.
• D-13: Plans should maximize parallelization -- backend models/API, admin UI, coaching UI, and scoring engine can be developed as parallel workstreams.

• System prompt engineering for HCP character fidelity (exact prompt structure, token budgets)
• SSE vs WebSocket choice for streaming (SSE recommended for text-only, simpler)
• Database schema details for HCP profiles, scenarios, sessions, messages, scores
• Scenario editor modal vs inline expand (Figma spec shows both options)
• Azure service config UI layout (PLAT-03 -- admin configures Azure connections)
• Session timer implementation details
• Responsive adaptations of 3-column F2F coaching layout for tablet/mobile

• Voice interaction (STT/TTS) -- Phase 3
• AI Avatar visual for HCP -- Phase 3
• Conference presentation mode -- Phase 3
• PDF export for scoring reports -- Phase 3+
• Training material upload and RAG grounding -- Phase 3 </user_constraints>

<phase_requirements>

Installation:

# Backend
cd backend
pip install sse-starlette>=2.0.0
# Add to pyproject.toml dependencies

# Frontend
cd frontend
npm install recharts @radix-ui/react-slider

backend/
├── app/
│   ├── api/
│   │   ├── hcp_profiles.py      # CRUD for HCP profiles (admin)
│   │   ├── scenarios.py          # CRUD for scenarios (admin)
│   │   ├── sessions.py           # Session lifecycle + streaming chat
│   │   ├── scoring.py            # Trigger scoring, get results
│   │   └── azure_config.py       # PLAT-03: Azure service connection management
│   ├── models/
│   │   ├── hcp_profile.py        # HcpProfile ORM model
│   │   ├── scenario.py           # Scenario ORM model
│   │   ├── session.py            # CoachingSession ORM model
│   │   ├── message.py            # SessionMessage ORM model
│   │   └── score.py              # SessionScore + ScoreDetail ORM models
│   ├── schemas/
│   │   ├── hcp_profile.py        # Pydantic schemas for HCP profiles
│   │   ├── scenario.py           # Pydantic schemas for scenarios
│   │   ├── session.py            # Pydantic schemas for sessions
│   │   └── score.py              # Pydantic schemas for scoring
│   ├── services/
│   │   ├── hcp_profile_service.py  # HCP profile business logic
│   │   ├── scenario_service.py     # Scenario business logic
│   │   ├── session_service.py      # Session lifecycle management
│   │   ├── scoring_service.py      # Post-session scoring orchestration
│   │   ├── prompt_builder.py       # System prompt construction for HCP personas
│   │   └── agents/
│   │       └── adapters/
│   │           ├── mock.py         # Enhanced mock with HCP personality templates (D-12)
│   │           ├── openai.py       # Azure OpenAI / OpenAI adapter
│   │           └── anthropic.py    # Anthropic Claude adapter
│   └── alembic/
│       └── versions/
│           └── xxxx_add_phase2_models.py  # Single migration for all Phase 2 models
frontend/
├── src/
│   ├── api/
│   │   ├── hcp-profiles.ts       # HCP profile API calls
│   │   ├── scenarios.ts          # Scenario API calls
│   │   ├── sessions.ts           # Session + streaming API calls
│   │   └── scoring.ts            # Scoring API calls
│   ├── components/
│   │   ├── coach/
│   │   │   ├── chat-area.tsx           # Chat message list + input
│   │   │   ├── chat-message.tsx        # Single message bubble
│   │   │   ├── chat-input.tsx          # Text input + send button
│   │   │   ├── scenario-panel.tsx      # Left panel: scenario + HCP info
│   │   │   ├── key-messages.tsx        # Key message checklist component
│   │   │   ├── hints-panel.tsx         # Right panel: coaching hints
│   │   │   ├── message-tracker.tsx     # Right panel: message delivery tracker
│   │   │   ├── session-timer.tsx       # Timer component
│   │   │   └── typing-indicator.tsx    # HCP typing animation
│   │   ├── scoring/
│   │   │   ├── radar-chart.tsx         # Recharts radar with current vs previous
│   │   │   ├── dimension-bars.tsx      # Color-coded score bars
│   │   │   ├── feedback-card.tsx       # Per-dimension strengths/weaknesses/suggestions
│   │   │   └── score-summary.tsx       # Overall score with grade
│   │   ├── admin/
│   │   │   ├── hcp-editor.tsx          # HCP profile form (right panel)
│   │   │   ├── hcp-list.tsx            # HCP list sidebar
│   │   │   ├── scenario-table.tsx      # Scenario management table
│   │   │   ├── scenario-editor.tsx     # Scenario editor (modal or inline)
│   │   │   ├── scoring-weights.tsx     # Linked sliders totaling 100%
│   │   │   ├── personality-sliders.tsx # Personality configuration sliders
│   │   │   ├── objection-list.tsx      # Editable objection list
│   │   │   └── test-chat-dialog.tsx    # Quick test chat for HCP personality (D-09)
│   │   └── ui/
│   │       ├── slider.tsx              # New: shadcn slider component (Radix)
│   │       └── textarea.tsx            # New: shadcn textarea component
│   ├── hooks/
│   │   ├── use-hcp-profiles.ts    # TanStack Query hooks for HCP profiles
│   │   ├── use-scenarios.ts       # TanStack Query hooks for scenarios
│   │   ├── use-session.ts         # TanStack Query hooks for coaching sessions
│   │   ├── use-scoring.ts         # TanStack Query hooks for scoring
│   │   └── use-sse.ts             # SSE connection hook for streaming
│   ├── pages/
│   │   ├── user/
│   │   │   ├── scenario-selection.tsx   # Scenario card grid (UI-05)
│   │   │   ├── f2f-coaching.tsx         # 3-column coaching page (UI-03)
│   │   │   └── scoring-feedback.tsx     # Post-session scoring report
│   │   └── admin/
│   │       ├── hcp-profiles.tsx         # HCP profile management page
│   │       ├── scenarios.tsx            # Scenario management page
│   │       └── azure-config.tsx         # Azure service configuration (PLAT-03)
│   ├── types/
│   │   ├── hcp.ts                 # HCP profile types
│   │   ├── scenario.ts           # Scenario types
│   │   ├── session.ts            # Session + message types
│   │   └── score.ts              # Score types
│   └── public/
│       └── locales/
│           ├── en-US/
│           │   ├── coach.json      # New i18n namespace for coaching
│           │   ├── admin.json      # New i18n namespace for admin
│           │   └── scoring.json    # New i18n namespace for scoring
│           └── zh-CN/
│               ├── coach.json
│               ├── admin.json
│               └── scoring.json

What: Server-Sent Events for streaming word-by-word AI HCP responses to the frontend. When to use: Every coaching interaction (D-01). Text-only, server-to-client streaming.

Backend pattern:

# backend/app/api/sessions.py
from sse_starlette.sse import EventSourceResponse

@router.post("/{session_id}/message")
async def send_message(
    session_id: str,
    request: SendMessageRequest,
    db: AsyncSession = Depends(get_db),
    user: User = Depends(get_current_user),
):
    """Send MR message and stream HCP response via SSE."""
    session = await session_service.get_session(db, session_id, user.id)
    # Save MR message
    await session_service.save_message(db, session_id, "user", request.message)

    async def event_generator():
        adapter = registry.get("llm", settings.default_llm_provider)
        coach_request = CoachRequest(
            session_id=session_id,
            message=request.message,
            scenario_context=session.scenario.to_context(),
            hcp_profile=session.scenario.hcp_profile.to_prompt_dict(),
            scoring_criteria=session.scenario.scoring_weights,
        )
        full_response = ""
        async for event in adapter.execute(coach_request):
            if event.type == CoachEventType.TEXT:
                full_response += event.content
                yield {"event": "text", "data": event.content}
            elif event.type == CoachEventType.SUGGESTION:
                yield {"event": "hint", "data": json.dumps({"content": event.content, "metadata": event.metadata})}
            elif event.type == CoachEventType.DONE:
                # Save complete HCP response
                await session_service.save_message(db, session_id, "assistant", full_response)
                # Key message detection (D-03)
                key_messages_status = await session_service.detect_key_messages(db, session)
                yield {"event": "key_messages", "data": json.dumps(key_messages_status)}
                yield {"event": "done", "data": ""}

    return EventSourceResponse(event_generator())

Frontend SSE hook pattern:

// frontend/src/hooks/use-sse.ts
export function useSSEChat(sessionId: string) {
  const [isStreaming, setIsStreaming] = useState(false);

  const sendMessage = useCallback(async (message: string) => {
    setIsStreaming(true);
    const response = await fetch(`/api/v1/sessions/${sessionId}/message`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${localStorage.getItem("access_token")}`,
      },
      body: JSON.stringify({ message }),
    });

    const reader = response.body?.getReader();
    const decoder = new TextDecoder();
    // Parse SSE events from the stream...
  }, [sessionId]);

  return { sendMessage, isStreaming };
}

What: Coaching session progresses through defined states: created -> in_progress -> completed -> scored When to use: All session operations (COACH-01, COACH-09)

# Session status enum
class SessionStatus(str, Enum):
    CREATED = "created"           # Session initialized, not started
    IN_PROGRESS = "in_progress"   # Active conversation
    COMPLETED = "completed"       # Conversation ended, awaiting scoring
    SCORED = "scored"             # Scoring complete, feedback available

# State transitions (enforced in service layer):
# created -> in_progress (first message sent)
# in_progress -> completed (manual end or HCP-initiated end via D-06)
# completed -> scored (scoring service completes)
# scored -> (terminal, immutable per COACH-09)

What: Build a system prompt that enforces HCP personality, knowledge, and behavior from the profile. When to use: Every coaching adapter call (COACH-02, D-10)

# backend/app/services/prompt_builder.py
def build_hcp_system_prompt(
    hcp_profile: HcpProfile,
    scenario: Scenario,
    conversation_history: list[dict],
) -> str:
    """Construct system prompt enforcing strict HCP character adherence (D-10)."""
    return f"""You are {hcp_profile.name}, a {hcp_profile.specialty} at {hcp_profile.hospital}.

## Your Personality
- Type: {hcp_profile.personality_type} (you MUST behave this way consistently)
- Emotional State: {hcp_profile.emotional_state}
- Communication Style: {hcp_profile.communication_style}

## Your Knowledge Background
- Medical Expertise: {', '.join(hcp_profile.expertise_areas)}
- Prescribing Habits: {hcp_profile.prescribing_habits}
- Concerns: {hcp_profile.concerns}

## Your Typical Objections (USE THESE)
{chr(10).join(f'- {obj}' for obj in hcp_profile.objections)}

## Scenario Context
Product: {scenario.product}
Therapeutic Area: {scenario.therapeutic_area}

## Rules
1. Stay STRICTLY in character. Never break character or acknowledge being an AI.
2. If personality is "Skeptical", ALWAYS push back and demand evidence.
3. If personality is "Busy", keep responses short and show impatience.
4. Reference your medical background when questioning the MR.
5. Use your objections naturally in the conversation.
6. You may end the conversation when key topics have been sufficiently covered
   or session has run long (D-06): say something like "I need to see my next patient."
7. Respond in the same language the MR uses (Chinese or English).
"""

What: 5 sliders that always total 100%. When one increases, others decrease proportionally. When to use: Scenario editor scoring weight configuration (D-08, HCP-05, SCORE-05)

// frontend/src/components/admin/scoring-weights.tsx
interface ScoringWeights {
  key_message: number;
  objection_handling: number;
  communication: number;
  product_knowledge: number;
  scientific_info: number;
}

function adjustWeights(
  weights: ScoringWeights,
  changed: keyof ScoringWeights,
  newValue: number
): ScoringWeights {
  const oldValue = weights[changed];
  const diff = newValue - oldValue;
  const otherKeys = Object.keys(weights).filter(k => k !== changed) as (keyof ScoringWeights)[];
  const otherTotal = otherKeys.reduce((sum, k) => sum + weights[k], 0);

  if (otherTotal === 0) return { ...weights, [changed]: 100 };

  const result = { ...weights, [changed]: newValue };
  for (const key of otherKeys) {
    const proportion = weights[key] / otherTotal;
    result[key] = Math.max(0, Math.round(weights[key] - diff * proportion));
  }
  // Fix rounding errors to ensure sum = 100
  const currentTotal = Object.values(result).reduce((a, b) => a + b, 0);
  if (currentTotal !== 100) {
    const adjustKey = otherKeys[0]!;
    result[adjustKey] += 100 - currentTotal;
  }
  return result;
}

What: After session ends, send full transcript to AI for multi-dimensional scoring (D-04). When to use: When session transitions to completed status (SCORE-01, SCORE-02)

# backend/app/services/scoring_service.py
SCORING_PROMPT = """Analyze this conversation between an MR and HCP.
Score each dimension from 0-100 based on the scoring criteria below.

## Dimensions and Weights
{dimensions_with_weights}

## Scoring Criteria
- Key Message Delivery: Were the key messages delivered clearly? Which ones were missed?
- Objection Handling: How well did the MR handle HCP objections?
- Communication Skills: Professional tone, active listening, rapport building?
- Product Knowledge: Accuracy of product information shared?
- Scientific Information: Quality of clinical/scientific data referenced?

## Conversation Transcript
{transcript}

## Key Messages Expected
{key_messages}

Respond in JSON format:
{{
  "overall_score": number,
  "dimensions": [
    {{
      "name": "Key Message Delivery",
      "score": number,
      "weight": number,
      "strengths": [{{ "text": "...", "quote": "MR said: ..." }}],
      "weaknesses": [{{ "text": "...", "quote": "When HCP asked: ..." }}],
      "suggestions": ["..."]
    }}
  ]
}}
"""

• Inline useQuery in components: Always create domain-specific hooks in src/hooks/. The existing use-auth.ts demonstrates the pattern.
• Synchronous database calls: ALL backend functions must be async def. Never use synchronous SQLAlchemy.
• Mutable completed sessions: Once a session is completed or scored, no messages can be added (COACH-09). Enforce in service layer, not just API.
• Hardcoded AI prompts in adapters: System prompts belong in prompt_builder.py, not inside adapter code. Adapters receive the prompt via CoachRequest.
• Missing i18n: All new UI text MUST use translation keys. Add new namespaces (coach, admin, scoring) to i18n/index.ts.
• Missing render_as_batch=True: All Alembic migrations must use batch mode for SQLite compatibility (Gotcha #1).
• Static routes after parameterized: In FastAPI, put /sessions/active before /sessions/{id} (Gotcha #3).
• Forgetting to import models in alembic/env.py: New models MUST be imported in env.py for autogenerate to detect them (Gotcha #7).

class HcpProfile(Base, TimestampMixin):
    __tablename__ = "hcp_profiles"

    name: Mapped[str] = mapped_column(String(255), nullable=False)
    specialty: Mapped[str] = mapped_column(String(100), nullable=False)
    hospital: Mapped[str] = mapped_column(String(255), default="")
    title: Mapped[str] = mapped_column(String(100), default="")
    avatar_url: Mapped[str] = mapped_column(String(500), default="")

    # Personality (D-07, D-10)
    personality_type: Mapped[str] = mapped_column(String(50), default="friendly")
    emotional_state: Mapped[int] = mapped_column(default=50)  # 0=neutral, 100=resistant
    communication_style: Mapped[int] = mapped_column(default=50)  # 0=direct, 100=indirect

    # Knowledge (HCP-01)
    expertise_areas: Mapped[str] = mapped_column(Text, default="[]")  # JSON array
    prescribing_habits: Mapped[str] = mapped_column(Text, default="")
    concerns: Mapped[str] = mapped_column(Text, default="")

    # Interaction Rules (HCP-02)
    objections: Mapped[str] = mapped_column(Text, default="[]")  # JSON array
    probe_topics: Mapped[str] = mapped_column(Text, default="[]")  # JSON array
    difficulty: Mapped[str] = mapped_column(String(20), default="medium")

    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
    created_by: Mapped[str] = mapped_column(String(36), ForeignKey("users.id"))

class Scenario(Base, TimestampMixin):
    __tablename__ = "scenarios"

    name: Mapped[str] = mapped_column(String(255), nullable=False)
    description: Mapped[str] = mapped_column(Text, default="")
    product: Mapped[str] = mapped_column(String(255), nullable=False)
    therapeutic_area: Mapped[str] = mapped_column(String(255), default="")
    mode: Mapped[str] = mapped_column(String(20), default="f2f")  # f2f / conference / both
    difficulty: Mapped[str] = mapped_column(String(20), default="medium")
    status: Mapped[str] = mapped_column(String(20), default="draft")  # draft / active

    # Assigned HCP (HCP-04)
    hcp_profile_id: Mapped[str] = mapped_column(String(36), ForeignKey("hcp_profiles.id"))

    # Key Messages (HCP-03)
    key_messages: Mapped[str] = mapped_column(Text, default="[]")  # JSON array

    # Scoring Weights (HCP-05, SCORE-05, D-08) -- must total 100
    weight_key_message: Mapped[int] = mapped_column(default=30)
    weight_objection_handling: Mapped[int] = mapped_column(default=25)
    weight_communication: Mapped[int] = mapped_column(default=20)
    weight_product_knowledge: Mapped[int] = mapped_column(default=15)
    weight_scientific_info: Mapped[int] = mapped_column(default=10)
    pass_threshold: Mapped[int] = mapped_column(default=70)

    created_by: Mapped[str] = mapped_column(String(36), ForeignKey("users.id"))

class CoachingSession(Base, TimestampMixin):
    __tablename__ = "coaching_sessions"

    user_id: Mapped[str] = mapped_column(String(36), ForeignKey("users.id"), nullable=False)
    scenario_id: Mapped[str] = mapped_column(String(36), ForeignKey("scenarios.id"), nullable=False)
    status: Mapped[str] = mapped_column(String(20), default="created")
    # created -> in_progress -> completed -> scored

    started_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
    completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
    duration_seconds: Mapped[int | None] = mapped_column(nullable=True)

    # Key message tracking (COACH-03, D-03)
    key_messages_status: Mapped[str] = mapped_column(Text, default="[]")  # JSON: [{message, delivered, detected_at}]

    # Overall score (filled after scoring)
    overall_score: Mapped[float | None] = mapped_column(nullable=True)
    passed: Mapped[bool | None] = mapped_column(nullable=True)

class SessionMessage(Base, TimestampMixin):
    __tablename__ = "session_messages"

    session_id: Mapped[str] = mapped_column(String(36), ForeignKey("coaching_sessions.id"), nullable=False)
    role: Mapped[str] = mapped_column(String(20), nullable=False)  # "user" or "assistant"
    content: Mapped[str] = mapped_column(Text, nullable=False)
    message_index: Mapped[int] = mapped_column(nullable=False)  # Ordering within session

class SessionScore(Base, TimestampMixin):
    __tablename__ = "session_scores"

    session_id: Mapped[str] = mapped_column(String(36), ForeignKey("coaching_sessions.id"), unique=True)
    overall_score: Mapped[float] = mapped_column(nullable=False)
    passed: Mapped[bool] = mapped_column(nullable=False)
    feedback_summary: Mapped[str] = mapped_column(Text, default="")

class ScoreDetail(Base, TimestampMixin):
    __tablename__ = "score_details"

    score_id: Mapped[str] = mapped_column(String(36), ForeignKey("session_scores.id"), nullable=False)
    dimension: Mapped[str] = mapped_column(String(50), nullable=False)
    score: Mapped[float] = mapped_column(nullable=False)
    weight: Mapped[int] = mapped_column(nullable=False)
    strengths: Mapped[str] = mapped_column(Text, default="[]")     # JSON array of {text, quote}
    weaknesses: Mapped[str] = mapped_column(Text, default="[]")    # JSON array of {text, quote}
    suggestions: Mapped[str] = mapped_column(Text, default="[]")   # JSON array of strings

Note on JSON columns: SQLite does not have native JSON type. Use Text columns with JSON serialization. For PostgreSQL in production, these can use JSONB. The service layer handles serialization/deserialization.

Key insight: The Phase 1 foundation provides most infrastructure. Phase 2 is about domain logic and UI, not plumbing.

What goes wrong: Vite's dev proxy may buffer SSE responses, causing all text to arrive at once instead of streaming. Why it happens: HTTP proxies can buffer chunked responses. The Vite proxy config already has ws: true but may need SSE-specific headers. How to avoid: Ensure the SSE response includes Cache-Control: no-cache and X-Accel-Buffering: no headers. The sse-starlette library handles this by default, but test early. In nginx production config, add proxy_buffering off. Warning signs: Chat messages appear all at once after a delay instead of streaming word-by-word.

What goes wrong: Adding new CoachEventType values breaks the existing MockCoachingAdapter. Why it happens: The mock adapter yields specific event types. New types (e.g., KEY_MESSAGE_UPDATE, HINT) need handling. How to avoid: Add new event types but keep existing ones. The mock adapter should be enhanced (D-12) but must still pass existing tests. New event types are optional for adapters to emit. Warning signs: Mock adapter stops working, test failures.

What goes wrong: Admin saves scenario with weights totaling 95% or 105%. Why it happens: Rounding errors in linked slider logic, or direct API manipulation. How to avoid: Validate sum === 100 in both frontend (linked slider logic) AND backend (Pydantic validator). Backend is the source of truth. Use @field_validator to reject weights not summing to 100. Warning signs: Weighted scores produce unexpected results.

What goes wrong: Long coaching sessions exceed the LLM context window (D-11 requires full history). Why it happens: Each turn adds ~100-500 tokens. A 30-turn conversation could be 15K+ tokens plus the system prompt. How to avoid: Track token count per session. If approaching limit (e.g., 80% of context window), truncate older messages while keeping system prompt and last N turns. Log a warning when truncation occurs. For OpenAI, use tiktoken for accurate counting. For mock adapter, this is not an issue. Warning signs: API errors from the LLM provider about context length.

What goes wrong: Trying to query JSON array contents with SQL (e.g., filtering scenarios by key message content). Why it happens: SQLite has limited JSON support compared to PostgreSQL. How to avoid: For Phase 2, keep JSON columns as opaque blobs -- load the full record and filter in Python. Don't try to do JSON path queries in SQLite. PostgreSQL migration can add JSONB indexes later. Warning signs: Alembic migration failures, query performance issues.

What goes wrong: alembic revision --autogenerate generates empty migration. Why it happens: Alembic only detects models imported in env.py. Currently only User is imported (Gotcha #7). How to avoid: Import ALL new models in alembic/env.py: from app.models import Base, User, HcpProfile, Scenario, CoachingSession, SessionMessage, SessionScore, ScoreDetail Warning signs: Migration file has no operations in upgrade().

What goes wrong: New translation keys show raw key strings instead of translated text. Why it happens: New namespaces (coach, admin, scoring) not added to the i18n init config. How to avoid: Update frontend/src/i18n/index.ts to include new namespaces: ns: ["common", "auth", "nav", "coach", "admin", "scoring"]. Create corresponding JSON files in both en-US/ and zh-CN/ locale directories. Warning signs: UI shows coach:startSession instead of "Start Session".

What goes wrong: MR sends a message at the same time as clicking "End Session", creating an inconsistent state. Why it happens: Concurrent requests -- one to send message, one to end session. How to avoid: Use optimistic locking or check session status at the beginning of every message send. If status is not in_progress, reject with 409 Conflict. The completed_at timestamp serves as the lock. Warning signs: Messages appearing after session is marked as completed.

// frontend/src/hooks/use-sse.ts
// Pattern for consuming SSE stream from FastAPI
export function useSSEStream() {
  const streamMessage = useCallback(
    async (
      sessionId: string,
      message: string,
      onText: (chunk: string) => void,
      onHint: (hint: CoachingHint) => void,
      onKeyMessages: (status: KeyMessageStatus[]) => void,
      onDone: () => void
    ) => {
      const token = localStorage.getItem("access_token");
      const response = await fetch(`/api/v1/sessions/${sessionId}/message`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${token}`,
        },
        body: JSON.stringify({ message }),
      });

      if (!response.ok || !response.body) throw new Error("Stream failed");

      const reader = response.body.getReader();
      const decoder = new TextDecoder();
      let buffer = "";

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        buffer += decoder.decode(value, { stream: true });
        const lines = buffer.split("\n");
        buffer = lines.pop() ?? "";

        for (const line of lines) {
          if (line.startsWith("event: ")) {
            // Parse SSE event type
          } else if (line.startsWith("data: ")) {
            const data = line.slice(6);
            // Handle based on current event type
          }
        }
      }
    },
    []
  );

  return { streamMessage };
}

# backend/app/api/hcp_profiles.py
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession

from app.dependencies import get_db, require_role
from app.models.user import User
from app.schemas.hcp_profile import HcpProfileCreate, HcpProfileResponse, HcpProfileUpdate
from app.services import hcp_profile_service
from app.utils.pagination import PaginatedResponse

router = APIRouter(prefix="/hcp-profiles", tags=["hcp-profiles"])

@router.get("", response_model=PaginatedResponse[HcpProfileResponse])
async def list_profiles(
    page: int = 1,
    page_size: int = 20,
    db: AsyncSession = Depends(get_db),
    user: User = Depends(require_role("admin")),
):
    """List all HCP profiles (admin only)."""
    return await hcp_profile_service.list_profiles(db, page, page_size)

@router.post("", response_model=HcpProfileResponse, status_code=201)
async def create_profile(
    data: HcpProfileCreate,
    db: AsyncSession = Depends(get_db),
    user: User = Depends(require_role("admin")),
):
    """Create a new HCP profile (admin only)."""
    return await hcp_profile_service.create_profile(db, data, user.id)

@router.get("/{profile_id}", response_model=HcpProfileResponse)
async def get_profile(
    profile_id: str,
    db: AsyncSession = Depends(get_db),
    user: User = Depends(require_role("admin")),
):
    """Get a specific HCP profile."""
    return await hcp_profile_service.get_profile(db, profile_id)

@router.put("/{profile_id}", response_model=HcpProfileResponse)
async def update_profile(
    profile_id: str,
    data: HcpProfileUpdate,
    db: AsyncSession = Depends(get_db),
    user: User = Depends(require_role("admin")),
):
    """Update an HCP profile."""
    return await hcp_profile_service.update_profile(db, profile_id, data)

@router.delete("/{profile_id}", status_code=204)
async def delete_profile(
    profile_id: str,
    db: AsyncSession = Depends(get_db),
    user: User = Depends(require_role("admin")),
):
    """Delete an HCP profile."""
    await hcp_profile_service.delete_profile(db, profile_id)

// frontend/src/hooks/use-hcp-profiles.ts
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { hcpProfilesApi } from "@/api/hcp-profiles";
import type { HcpProfileCreate, HcpProfileUpdate } from "@/types/hcp";

export function useHcpProfiles(page = 1, pageSize = 20) {
  return useQuery({
    queryKey: ["hcp-profiles", page, pageSize],
    queryFn: () => hcpProfilesApi.list(page, pageSize),
  });
}

export function useHcpProfile(id: string) {
  return useQuery({
    queryKey: ["hcp-profiles", id],
    queryFn: () => hcpProfilesApi.get(id),
    enabled: !!id,
  });
}

export function useCreateHcpProfile() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: HcpProfileCreate) => hcpProfilesApi.create(data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["hcp-profiles"] });
    },
  });
}

export function useUpdateHcpProfile(id: string) {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: HcpProfileUpdate) => hcpProfilesApi.update(id, data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["hcp-profiles"] });
    },
  });
}

// frontend/src/pages/user/f2f-coaching.tsx
// Mobile: stacked with Sheet overlays for left/right panels
// Tablet: left panel collapses, right panel as Sheet
// Desktop: full 3-column layout

export default function F2FCoachingPage() {
  return (
    <div className="flex h-[calc(100vh-4rem)] overflow-hidden">
      {/* Left Panel: hidden on mobile, shown as sidebar on md+ */}
      <aside className="hidden w-[280px] shrink-0 overflow-y-auto border-r bg-white md:block">
        <ScenarioPanel />
        <KeyMessages />
      </aside>

      {/* Center Panel: always visible */}
      <main className="flex flex-1 flex-col">
        <SessionHeader /> {/* Timer + End Session button */}
        <ChatArea />     {/* Scrollable message list */}
        <ChatInput />    {/* Fixed at bottom */}
      </main>

      {/* Right Panel: hidden on mobile/tablet, shown on lg+ */}
      <aside className="hidden w-[260px] shrink-0 overflow-y-auto border-l bg-white lg:block">
        <HintsPanel />
        <MessageTracker />
      </aside>

      {/* Mobile: Sheet overlays for left/right panels triggered by icon buttons */}
    </div>
  );
}

Deprecated/outdated:

• @app.on_event("startup"): Replaced by lifespan context manager (already using correct pattern)
• Pydantic v1 class Config: Must use model_config = ConfigDict(from_attributes=True) (v2 pattern)
• Optional[X]: Use X | None (modern Python 3.11+ union syntax, already enforced)

1. Mock Adapter Realism Level (D-12)

   • What we know: Mock must feel "somewhat real even without Azure OpenAI" for demo this week
   • What's unclear: Exact number of template responses needed, how much randomization
   • Recommendation: Build 5-8 response templates per personality type (Skeptical, Friendly, Busy, Detail-oriented, Resistant). Each template has 3-4 variations. Use conversation turn count and detected keywords to select appropriate template. This is sufficient for demo quality.

2. Session Timer Behavior

   • What we know: Timer shown in coaching page header (Figma 04), counts up from session start
   • What's unclear: Whether timer should auto-end session after a maximum duration
   • Recommendation: Timer counts up. No auto-end. Session ends via manual button or HCP-initiated (D-06). Display timer as MM:SS format.

3. PLAT-03 Azure Config Storage

   • What we know: Admin configures Azure connections (OpenAI, Speech, Avatar) from web UI with connection testing
   • What's unclear: Whether to store in database (runtime-updatable) or .env (requires restart)
   • Recommendation: Store in database azure_config table. On save, update in-memory settings. Provide "Test Connection" button that pings the Azure endpoint. Restart not needed. This is more admin-friendly.

4. Scenario Editor: Modal vs Inline

   • What we know: Figma spec 09 shows both options. Admin managing many scenarios.
   • What's unclear: Which is better UX for this use case.
   • Recommendation: Use Dialog (modal) for scenario editor. The table view stays visible as context. HCP profiles use the master-detail pattern (list + editor) since profiles have more fields and need visual context (personality sliders).

These directives from CLAUDE.md MUST be followed by the planner:

1. Async everywhere: All new backend functions must be async def with AsyncSession
2. Pydantic v2: Use model_config = ConfigDict(from_attributes=True) on all response schemas
3. Exception raisers: Use -> NoReturn annotation on functions that always raise
4. Route ordering: Static paths before parameterized (/defaults before /{id})
5. Create returns 201, Delete returns 204
6. Service layer: Business logic in services, routers only handle HTTP
7. No raw SQL: Use SQLAlchemy ORM or Alembic migrations
8. TypeScript strict: No any types, no unused variables
9. TanStack Query hooks per domain: No inline useQuery in components
10. Path alias @/: For all imports from src/
11. cn() utility: For conditional class composition
12. No Redux: TanStack Query for server state, lightweight store for auth
13. Conventional commits: feat:, fix:, docs:, test:
14. Alembic for ALL schema changes: Never modify DB schema without migration
15. Never delete database file: Use migrations to fix schema issues
16. render_as_batch=True: Required in all Alembic migrations for SQLite compatibility
17. All models use TimestampMixin: UUID id + created_at + updated_at
18. i18n required: All UI text externalized via react-i18next (zh-CN + en-US)
19. Pre-commit checks: ruff check ., ruff format --check ., pytest -v, npx tsc -b, npm run build
20. Barrel exports: index.ts for component directories
21. Import all models in alembic/env.py: Required for autogenerate

Missing dependencies with no fallback:

• None -- all blocking dependencies are available or have mock fallbacks

Missing dependencies with fallback:

• Azure OpenAI endpoint: Not configured, but mock adapter provides demo-quality responses (D-12)
• recharts and @radix-ui/react-slider: Need npm install, but this is a plan-time action, not a blocker

• Existing codebase: backend/app/services/agents/base.py, registry.py, adapters/mock.py -- adapter pattern
• Existing codebase: backend/app/models/base.py, user.py -- ORM model pattern
• Existing codebase: backend/app/api/auth.py -- router pattern with DI
• Existing codebase: frontend/src/hooks/use-auth.ts -- TanStack Query hook pattern
• Existing codebase: frontend/src/stores/auth-store.ts -- useSyncExternalStore pattern
• Existing codebase: frontend/src/components/ui/index.ts -- 17 shadcn/ui components available
• Figma specs: docs/figma-prompts/03-scenario-selection.md, 04-f2f-coaching.md, 06-scoring-feedback.md, 09-admin-hcp-scenarios.md
• Package versions verified via npm view and pip show against installed versions

• sse-starlette library: Installed on system (v2.3.5), well-known FastAPI SSE library
• recharts: npm registry confirms v3.8.0, widely used React charting library
• Capgemini reference architecture: docs/capgemini-ai-coach-solution.md -- scoring dimensions and interaction flow

• System prompt engineering patterns: Based on training data, not verified against current best practices. The exact prompt structure should be iteratively refined during development.
• Token counting with tiktoken: Based on training knowledge. Verify current API when implementing context window management.

Confidence breakdown:

• Standard stack: HIGH -- all libraries verified via npm/pip, existing patterns confirmed in codebase
• Architecture: HIGH -- follows established Phase 1 patterns exactly, Figma specs provide clear layout guidance
• Database schema: HIGH -- follows existing User model pattern with TimestampMixin, relationships are straightforward
• Pitfalls: MEDIUM -- SSE proxy behavior needs runtime testing, token limits depend on chosen model
• System prompts: LOW -- prompt engineering is iterative, initial templates are starting points

Research date: 2026-03-24 Valid until: 2026-04-24 (stable domain, existing patterns)

Visual and interaction contract for F2F Text Coaching and Scoring. Generated by gsd-ui-researcher, verified by gsd-ui-checker. Authoritative source: Figma Make exports in figma-make/ directory + existing Phase 1 design tokens.

Avatar, Badge, Button, Card, Checkbox, Dialog, DropdownMenu, Form, Input, Label, Select, Separator, Sheet, Skeleton, Sonner, Switch, Tooltip

Declared values (multiples of 4, inherited from Phase 1 Figma Make design tokens):

Exceptions:

• Left panel width: 280px (fixed, collapsible to 48px)
• Right panel width: 260px (fixed, collapsible to 48px)
• Avatar display area height: 240px (h-[240px])
• Top bar height: 56px (h-14)
• Mic/Send button: 44px (h-11 w-11) touch target
• HCP avatar in left panel: 60px (h-[60px] w-[60px])
• HCP avatar in scenario card: 80px
• HCP avatar in editor: 120px
• Chat max width: max-w-4xl (896px)
• Chat bubble max width: max-w-[70%]

All values extracted from Figma Make theme.css base layer and Figma Make component files. Consolidated to 4 sizes and 2 weights for design consistency.

Font stack: 'Inter', 'Noto Sans SC', sans-serif (via --font-sans token). Mono font for timer: 'JetBrains Mono', 'Fira Code', monospace (via --font-mono token).

Weight differentiation guide:

• 400 (normal): Body text, descriptions, metadata, timestamps, placeholder text, hints
• 600 (semibold): Headings, labels, buttons, emphasis, display numbers, card titles, panel headers

Size differentiation for former "Small" elements:

• Timestamps, hints, badge text, scoring criteria values, key message checklist items: Use 14px (text-sm) at weight 400 with text-muted-foreground or opacity-70 to visually distinguish from primary body text.

All values extracted from existing frontend/src/styles/index.css design tokens (established in Phase 1 from Figma Make theme).

Accent color (#1E40AF / bg-primary / bg-blue-600) is reserved exclusively for:

1. Primary action buttons ("Start Training", "Save Profile", "Save Scenario", "Send")
2. Active navigation items and tab indicators
3. HCP avatar fallback background (bg-blue-100 text-blue-700 for light, bg-blue-600 text-white for large)
4. Radar chart current-session fill
5. Chat bubble for HCP messages (bg-blue-500)
6. Active mode toggle buttons
7. In-progress message tracker dot (bg-blue-600)
8. Scenario card header gradient

Source: figma-make/Scenario Selection Page Design/src/app/pages/user/Training.tsx + docs/figma-prompts/03-scenario-selection.md

Layout: Standard page within user layout shell (Phase 1).

• Page padding: p-4 lg:p-8
• Max width: max-w-7xl mx-auto
• Title: text-3xl font-semibold text-gray-900 mb-8

Scenario Card Grid:

• Grid: grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6
• Card: bg-white rounded-xl shadow-sm border border-gray-200 overflow-hidden hover:shadow-md transition-shadow
• Card header: h-48 bg-gradient-to-br from-blue-500 to-blue-600 with centered PlayCircle icon (w-16 h-16 text-white opacity-80)
• Card body: p-6
• Title: text-lg font-semibold text-gray-900 mb-2
• Description: text-sm text-gray-600 mb-4
• Metadata row: flex items-center gap-4 mb-4 text-sm text-gray-600 with Clock + Star icons
• Difficulty badge: px-3 py-1 bg-blue-100 text-blue-700 rounded-full text-sm font-semibold
• Start button: px-4 py-2 bg-blue-600 text-white rounded-lg text-base font-semibold hover:bg-blue-700 transition-colors

Filter Bar (from Figma prompt, not yet in Training.tsx):

• Tabs: "F2F Training" (active) | "Conference Training"
• Filters: Product dropdown, Difficulty dropdown, Specialty dropdown, Search input
• Layout: flex items-center gap-4 mb-6

Empty State: Use EmptyState component pattern from Figma Make Design System:

• Container: flex flex-col items-center justify-center py-12 px-4 text-center
• Icon: 80px circle (w-20 h-20 rounded-full bg-muted) with centered icon (w-10 h-10 text-muted-foreground)
• Title: text-lg font-semibold text-foreground mb-2
• Body: text-sm text-muted-foreground mb-6 max-w-md

Source: figma-make/F2F HCP Training Page Design/src/app/ (all components)

Layout: Full viewport, no scroll. Three-panel side-by-side.

• Container: h-screen w-screen overflow-hidden flex bg-white

Left Panel (Training Panel):

• Expanded: w-[280px] bg-slate-50 border-r border-slate-200 p-4 overflow-y-auto
• Collapsed: w-12 bg-slate-50 border-r border-slate-200 flex flex-col items-center pt-4
• Toggle: Button variant="ghost" size="icon" with ChevronLeft
• Sections (each a Card with mb-4):
  1. Scenario Briefing: CardTitle text-sm, content space-y-2 text-sm
  2. HCP Profile: Avatar h-[60px] w-[60px], fallback bg-blue-100 text-blue-700, name font-semibold, details text-sm text-slate-600
  3. Key Messages: Checkbox + label list, checkbox mt-0.5, label text-sm text-slate-700 cursor-pointer leading-relaxed
  4. Scoring Criteria: Key-value pairs flex justify-between, label text-slate-600, value font-semibold, all text-sm

Center Panel (Chat):

• Container: flex-1 flex flex-col bg-white
• Top bar: h-14 border-b border-slate-200 px-6 flex items-center justify-between
  • Timer: flex items-center gap-2 text-slate-600, Clock icon h-4 w-4, time in font-mono
  • End Session: Button variant="destructive" size="sm" with AlertCircle icon
• Avatar display: h-[240px] bg-slate-900 relative flex items-center justify-center
  • Avatar: h-32 w-32 border-4 border-white
  • Label badge: px-3 py-1 bg-slate-800/80 rounded text-white text-sm
  • Toggle: absolute top-3 right-3 with Switch + Label in bg-slate-800/80 px-3 py-1.5 rounded
• Chat area: ScrollArea className="flex-1 p-6", messages in space-y-4 max-w-4xl mx-auto
  • HCP bubble: max-w-[70%] rounded-lg px-4 py-2.5 bg-blue-500 text-white
  • MR bubble: max-w-[70%] rounded-lg px-4 py-2.5 bg-slate-200 text-slate-900
  • Message text: text-sm leading-relaxed
  • Timestamp: text-sm opacity-70 mt-1 block text-muted-foreground
  • Typing indicator: bg-blue-500 text-white rounded-lg px-4 py-2.5 with 3 dots: w-2 h-2 bg-white rounded-full animate-bounce with staggered delays
• Input area: border-t border-slate-200 p-4 bg-slate-50
  • Layout: max-w-4xl mx-auto space-y-3
  • Row: flex items-center gap-3
  • Textarea: flex-1 min-h-[44px] max-h-32 resize-none
  • Mic button: h-11 w-11 rounded-full, idle=bg-blue-600 hover:bg-blue-700, recording=bg-red-600 hover:bg-red-700 animate-pulse, processing=bg-yellow-600 hover:bg-yellow-700
  • Send button: h-11 w-11 rounded-full (primary), aria-label="Send message"
  • Mode toggle: px-3 py-1 rounded text-sm, active=bg-blue-600 text-white, inactive=bg-slate-200 text-slate-600

Right Panel (Coaching Panel):

• Expanded: w-[260px] bg-slate-50 border-l border-slate-200 p-4 overflow-y-auto
• Collapsed: w-12 bg-slate-50 border-l border-slate-200 flex flex-col items-center pt-4
• Toggle: Button variant="ghost" size="icon" with ChevronRight
• Sections:
  1. AI Coach Hints: Card className="mb-4 bg-yellow-50 border-yellow-200", hints text-sm text-slate-700 leading-relaxed
  2. Message Tracker: Status icons — delivered: Check h-4 w-4 text-green-600, in-progress: div h-2 w-2 bg-blue-600 rounded-full, pending: Circle h-4 w-4 text-slate-400. Text color: delivered=text-green-700, in-progress=text-blue-700, pending=text-slate-500
  3. Session Stats: Key-value pairs flex justify-between text-sm

Source: docs/figma-prompts/06-scoring-feedback.md + Figma Make ScoreCard, DimensionBar, RadarChart components

Layout: Standard page within user layout shell.

• Page padding: p-4 lg:p-8
• Max width: max-w-7xl mx-auto

Top Section:

• Overall score: Large number (text-3xl font-semibold) with circular progress ring (recharts PieChart or custom SVG), Grade badge
• Trend indicator: flex items-center gap-1 text-sm text-strength with TrendingUp icon
• Session info: text-sm text-muted-foreground

Two-Column Layout: grid grid-cols-1 lg:grid-cols-2 gap-8

Left Column:

• Radar chart: h-80 (320px), ResponsiveContainer with recharts RadarChart
  • Grid stroke: #E5E7EB
  • Angle axis tick: fill: '#64748B', fontSize: 14
  • Radius axis tick: fill: '#64748B', fontSize: 14
  • Current session: stroke="#1E40AF" fill="#1E40AF" fillOpacity={0.5}
  • Previous session: stroke="#475569" strokeDasharray="5 5" fill="none" (overlay comparison)
• Dimension bars (below radar): Stack of DimensionBar components
  • Label + score: flex items-center justify-between, label text-sm, score text-sm font-semibold
  • Bar track: w-full h-2 bg-accent rounded-full overflow-hidden
  • Bar fill: h-full rounded-full transition-all duration-500
  • Color by score: >= 80 bg-strength, 60-79 bg-weakness, < 60 bg-destructive

Right Column:

• Scrollable feedback cards, one per dimension
• Each card (Card component):
  • Header: Dimension name + score
  • Strengths: text-strength with Check icon, quoted text from conversation
  • Areas to Improve: text-weakness with X icon, quoted text
  • Suggestions: text-improvement with Lightbulb icon, actionable text

Bottom Action Bar: flex items-center justify-end gap-4 mt-8 pt-6 border-t

• "Try Again": Button variant="outline"
• "Export PDF": Button variant="outline" (disabled for Phase 2 — Phase 3+)
• "Share with Manager": Button variant="outline" (disabled for Phase 2)
• "Back to Dashboard": Button variant="default" (primary)

Source: docs/figma-prompts/09-admin-hcp-scenarios.md

Layout: Two-panel within admin layout shell.

Left: HCP List Sidebar (300px)

• Container: w-[300px] border-r border-slate-200 flex flex-col
• Search: Input at top with p-4
• List: Scrollable, each item shows avatar (40px) + name + specialty
• Active item: bg-blue-50 border-l-2 border-blue-600
• Bottom: "Create New HCP" button, full-width, Button variant="outline"

Right: HCP Editor Form (flex-1)

• Container: flex-1 p-6 overflow-y-auto
• Form sections use Card components with mb-6:
  1. Portrait: Avatar circle 120px with upload overlay
  2. Identity: Name, Specialty (Select), Hospital, Title — grid grid-cols-2 gap-4
  3. Personality (Card): Personality Type (Select dropdown), Emotional State (Slider), Communication Style (Slider)
  4. Knowledge (Card): Multi-select tag input for expertise, textareas for habits and concerns
  5. Interaction Rules (Card): Editable objection list, key topics list, difficulty radio
• Bottom actions: flex items-center gap-3
  • "Save Profile": Button variant="default" (primary)
  • "Test Chat": Button variant="outline" — opens Dialog with mini-chat
  • "Discard Changes": Button variant="ghost"

Source: docs/figma-prompts/09-admin-hcp-scenarios.md

Layout: Standard admin page.

• Top: Title + "Create Scenario" primary button + status filter (Select: All/Active/Draft)
• Table: Using DataTable pattern from Figma Make Design System
  • Columns: Name, Product, HCP (avatar + name), Mode (Badge: F2F/Conference), Difficulty (Badge), Status (StatusBadge), Actions (DropdownMenu)
  • Sortable columns: Name, Product, Difficulty
  • Pagination: flex items-center justify-between mt-4

Scenario Editor (Dialog modal):

• Form fields: Name, Description (Textarea), Product (Select), Therapeutic Area (Select), Assigned HCP (Select with avatar), Mode (radio), Key Messages (editable checklist), Scoring Weights (5 linked Sliders totaling 100%), Pass Threshold (Input type number, default 70)
• Actions: "Save Scenario" primary button, "Clone Scenario" outline button

Source: figma-make/Design System for SaaS/src/app/components/ServiceConfigCard.tsx

Layout: Standard admin page with stacked ServiceConfigCard components.

• Each service card: Expandable accordion pattern
  • Header: Icon (48px bg, bg-primary/10), name, status dot (green=active, gray=inactive, red=error), description
  • Expanded content: Form fields for endpoint, API key, model, region + "Test Connection" button
• Services: Azure OpenAI, Azure Speech (STT), Azure Speech (TTS), Azure AI Avatar, Azure Content Understanding

All UI text MUST use i18n translation keys. Values below are the en-US defaults. zh-CN translations must be provided in parallel.

These components from figma-make/Design System for SaaS/src/app/components/ should be implemented as shared components since they are used across multiple pages:

• All interactive elements must have visible focus rings (already enforced by outline-ring/50 base style)
• Chat bubbles must use role="log" and aria-live="polite" on the message container for screen reader announcement of new messages
• Typing indicator must use aria-label="HCP is typing" with aria-live="polite"
• Scoring dimension bars must include role="progressbar" with aria-valuenow, aria-valuemin="0", aria-valuemax="100"
• Panel collapse toggles must use aria-expanded and aria-controls
• Mic button states must use aria-label that changes with state ("Start recording" / "Recording..." / "Processing...")
• Send button must use aria-label="Send message" for screen reader accessibility
• All form inputs in admin pages must have associated labels (enforced by shadcn Form component)
• Color-coded scores must also have text labels (never rely on color alone)
• Keyboard: Enter sends message in chat, Shift+Enter for newline

• Dimension 1 Copywriting: PASS
• Dimension 2 Visuals: PASS
• Dimension 3 Color: PASS
• Dimension 4 Typography: PASS
• Dimension 5 Spacing: PASS
• Dimension 6 Registry Safety: PASS

Approval: pending

Phase Goal: An MR can select a scenario, have a text-based F2F conversation with an AI HCP that behaves according to its profile, and receive a multi-dimensional scored feedback report after the session Verified: 2026-03-24T21:00:00Z Status: passed Re-verification: No -- initial verification

Truths derived from ROADMAP.md Success Criteria for Phase 2.

Score: 5/5 truths verified

All 54 expected artifacts verified across 8 plans.

Orphaned requirements: None. All 18 requirement IDs from ROADMAP Phase 2 are accounted for across the 8 plans.

Notes: The only grep matches for "placeholder" were legitimate HTML input/select placeholder attributes in training.tsx and chat-area.tsx -- these are UI placeholder text, not stub code. No TODO/FIXME/empty returns found in any critical Phase 2 files.

Test: Log in as user, navigate to /user/training, select a scenario, click Start Training, send 3-4 messages, click End Session, verify redirect to scoring page with radar chart and feedback cards. Expected: Messages stream word-by-word, key message checklist updates, hints appear, scoring page shows radar chart with dimension scores and per-dimension feedback. Why human: Visual appearance, streaming animation timing, layout responsiveness, and user flow completion cannot be verified programmatically without a running server.

Test: Log in as admin, navigate to /admin/hcp-profiles, create a new HCP profile with personality sliders and objections. Navigate to /admin/scenarios, create a scenario with linked scoring weights. Expected: Forms validate correctly, weight sliders redistribute when one is moved, created items appear in lists. Why human: Form interaction behavior, slider redistribution UX, and data persistence confirmation need visual verification.

Test: Navigate to /admin/azure-config, enter a test endpoint URL and key, click Test Connection. Expected: Connection test runs and shows pass/fail status. Why human: Connection test UI feedback and error display need visual confirmation.

Test: Open training session page on mobile viewport (375px), tablet (768px), and desktop (1440px). Expected: 3-column layout collapses to single column on mobile with collapsible panels. Why human: Responsive breakpoint behavior cannot be verified without rendering.

No gaps found. All 5 observable truths are verified. All 54 artifacts exist, are substantive (real implementation, not stubs), and are properly wired. All 18 requirements mapped to Phase 2 are satisfied with implementation evidence. The frontend TypeScript build passes cleanly with zero errors and the production build succeeds. Backend models import without errors and Alembic migration exists.

The scoring service currently uses mock scoring logic (keyword matching and template feedback) rather than real LLM-based analysis. This is by design -- the mock adapter pattern allows the system to work end-to-end without Azure credentials, and real LLM scoring will be wired when the Azure OpenAI adapter is connected. This is not a gap as the architecture supports the swap via the adapter pattern established in Phase 1.

Verified: 2026-03-24T21:00:00Z Verifier: Claude (gsd-verifier)