docs/upskilling/extras/interview-service-rebuild-plan.md

Interview Service Rebuild Plan

Summary

Rebuild interview-service from scratch in its canonical location under services/ and preserve the current implementation as a reference-only archive.

This plan intentionally replaces the older avatar-heavy and client/media-split direction with a much smaller phase-1 service focused on:

• interview configuration and planning
• one Gemini Live session path
• transcript and turn persistence
• dual-track audio archival with S3 upload
• rubric-based review generation with historical comparison

The rebuilt service remains named interview-service. There is no v2 naming in code, docs, or runtime configuration.

Goals

• Keep the public API to exactly 3 surfaces:
  • POST /configure
  • WS /session/{session_id}
  • GET /review/{session_id}
• Preserve the product behaviors that matter:
  • persona- and interview-aware planning
  • bounded historical context reuse
  • Gemini Live interview execution
  • rubric scoring and review generation
  • S3 archival of session audio artifacts
  • historical comparison and carry-forward planning signals
• Remove operational and architectural bloat from phase 1.

Non-Goals

The phase-1 rebuild explicitly excludes:

• avatars
• screen share
• technical-quality video analysis
• Redis
• SSE
• external job queues or workers
• demo app code
• multi-mode runtimes
• fallback-heavy abstractions

Audio-only interviewing is the only live mode in scope.

Repository Transition

The repo transition should happen before implementation starts:

1. Rename the current service folder from services/interview-service to services/interview-service-reference.
2. Create a fresh services/interview-service folder beside it.
3. Treat interview-service-reference as a source of assets and selected logic only.
4. Do not refactor in place from the archived codebase.

Reference code may be copied only when it directly supports the reduced phase-1 scope, primarily:

• personas
• prompts
• rubric definitions
• selected planning logic
• selected review/scoring logic

Target Service Shape

Build a small FastAPI service with a narrow, obvious structure:

services/interview-service/
  app/
    api/
      configure.py
      session_ws.py
      review.py
    assets/
      personas/
      prompts/
      rubric/
    services/
      planning.py
      gemini_live.py
      review.py
      audio_archive.py
      storage.py
    db/
      models.py
      session.py
    core/
      config.py
      logging.py
    main.py
  alembic/
  tests/

Guiding rule: each module should map to one durable service concern. Avoid framework layers that exist only for optionality that phase 1 does not need.

Public API

POST /configure

Responsibilities:

• validate persona, interview type, duration, and context
• load bounded historical review context for the user
• build the interview plan using current config plus retained history signals
• persist the session row before live execution begins

Response should return:

• session_id
• normalized configuration
• opening prompt
• ordered question outline
• history summary used for planning

Planning output should remain explicit and bounded:

• opening prompt
• ordered base questions
• follow-up policy
• focus areas influenced by history

WS /session/{session_id}

This is the only live runtime path in phase 1.

Accepted inbound events:

• session.start
• audio.input
• session.finish

Outbound events:

• session.ready
• assistant.transcript
• assistant.audio
• candidate.transcript
• turn.saved
• session.completed
• error

Responsibilities:

• attach to the persisted session
• run Gemini Live relay for the interview
• persist turns as they occur
• write assistant and candidate audio into the archive pipeline
• finalize artifacts and upload to S3 on session.finish
• mark the session complete
• start in-process async review generation after completion

GET /review/{session_id}

Behavior:

• return status: processing until review generation finishes
• return the final review payload when available

Final payload should include:

• overall score
• rubric scores
• strengths
• weaknesses
• recommendations
• historical comparison
• carry-forward planning signals
• audio artifact metadata

This endpoint is read-only. It does not trigger new work.

Data Model

Keep only 4 tables.

interview_sessions

Fields:

• session id
• user and org identifiers
• interview configuration JSON
• status
• planning context JSON
• question plan JSON
• opening prompt
• created/updated/completed timestamps

Purpose:

• own the session lifecycle
• preserve normalized planning inputs and outputs

interview_turns

Fields:

• session id
• sequence
• speaker
• turn type
• transcript
• timing metadata
• Gemini or session metadata JSON

Purpose:

• preserve ordered transcript and turn-level execution state

interview_artifacts

Fields:

• session id
• artifact type
• S3 key
• mime type
• duration and size
• manifest metadata JSON
• created timestamp

Purpose:

• register all persisted review-related artifacts

interview_reviews

Fields:

• session id
• overall score
• rubric scores JSON
• summary
• strengths JSON
• weaknesses JSON
• recommendations JSON
• historical comparison JSON
• carry-forward planning signals JSON
• created timestamp

Purpose:

• cache the final review payload
• expose direct planning signals for the next configure call

Planning Logic

Planning behavior to preserve from the prior service:

• use recent completed interview history
• use aggregated recurring weak areas
• let low historical scores and repeated gaps influence question selection
• adjust question emphasis and difficulty based on prior performance

Planning constraints for the rebuild:

• bound history lookup to a small recent window
• summarize recurring weaknesses instead of loading unbounded detail
• keep planning output deterministic enough to inspect and test
• store the history summary actually used during planning

Expected planning artifacts:

• normalized interview configuration
• bounded history summary
• focus areas
• ordered base questions
• opening prompt
• follow-up policy

Review Logic

Review behavior to preserve:

• score against the retained rubric
• use transcripts together with session audio artifacts
• generate strengths, weaknesses, and recommendations
• compare against prior interviews
• emit carry-forward signals for the next session

Carry-forward planning signals should be explicit and reusable, for example:

• recurring weak areas
• rubric dimensions trending down
• recommended follow-up difficulty
• suggested topic emphasis for the next interview

The review service should persist the finished result once and let GET /review/{session_id} return that cached payload directly.

Audio Archival and S3 Layout

Phase 1 archives both sides of the session, not candidate-only audio.

Recommended S3 object layout:

interviews/{user_id}/{session_id}/session-dual.wav
interviews/{user_id}/{session_id}/session-mixed.mp3
interviews/{user_id}/{session_id}/manifest.json

Artifact roles:

• session-dual.wav is the canonical review source
• session-mixed.mp3 is a secondary convenience playback artifact
• manifest.json links session metadata, channel mapping, transcript/review references, and artifact properties

Channel mapping:

• channel 1 = assistant
• channel 2 = candidate

Implementation rules:

• assemble artifacts incrementally on disk
• never buffer the full session in memory
• finalize and upload all artifacts on session.finish
• persist artifact rows after successful upload with S3 key and metadata

Runtime Simplification

Keep runtime configuration intentionally small:

• database URL
• Gemini credentials and model
• S3 bucket settings
• review model settings
• temp directory
• history window size
• logging level

Operational decisions for phase 1:

• no Redis
• no SSE
• no external queue or worker process
• no polling orchestration endpoint beyond GET /review/{session_id}
• review generation starts as an in-process async task after session.finish

If review generation fails, the failure should be stored clearly enough for diagnosis and surfaced predictably through the review endpoint or logs.

Delivery Sequence

1. Archive the current service as interview-service-reference.
2. Scaffold a fresh interview-service.
3. Copy only personas, prompts, rubric, and the minimum selected planning/review logic.
4. Create the 4-table schema and initial migration.
5. Implement POST /configure.
6. Implement the Gemini Live WebSocket session path.
7. Add ordered turn persistence.
8. Add dual-track archive assembly, mixed export, and manifest generation.
9. Add S3 upload on session completion.
10. Start in-process review generation on session.finish.
11. Implement GET /review/{session_id}.
12. Validate the rebuilt service against the simplified phase-1 scope.

Test Plan

The initial test suite should prove the simplified contract end to end.

Core cases:

• POST /configure rejects invalid config
• POST /configure returns normalized config and history-aware planning output
• historical weak areas alter the next session question plan
• WS /session/{session_id} rejects invalid or missing sessions
• turns are persisted in correct sequence order
• assistant and candidate audio are both captured into the archive workflow
• session-dual.wav, session-mixed.mp3, and manifest.json are produced with correct metadata
• S3 upload stores expected keys and artifact rows
• session.finish marks the session complete and starts review generation
• GET /review/{session_id} returns processing before completion and a full payload afterward
• final review includes historical comparison and carry-forward planning signals
• the end-to-end flow works without Redis, SSE, or queue infrastructure

Acceptance Criteria

The rebuild is ready for phase-1 validation when all of the following are true:

• the service exposes only the 3 required public surfaces
• the archived implementation is preserved separately as interview-service-reference
• the new service has only the 4 required database tables
• planning uses bounded historical context and persists the exact planning summary used
• the WebSocket path is Gemini Live only
• both sides of the interview are archived into the canonical dual-track artifact
• artifacts are uploaded to S3 and registered in interview_artifacts
• review generation persists rubric-based output plus historical comparison
• the next configure call can reuse carry-forward signals directly
• the service runs without Redis, SSE, or external worker infrastructure

Assumptions and Defaults

• Service name remains interview-service.
• The old implementation is preserved only as interview-service-reference.
• Audio-only interviewing is the only live mode in phase 1.
• Avatars, screen share, and technical-quality video analysis are deferred.
• Historical context is bounded to a recent window plus aggregated weak-area summaries.
• Review generation runs asynchronously inside the web process.
• session-dual.wav is the canonical review artifact.
• session-mixed.mp3 exists as a convenience artifact, not the source of truth.

Recommended Next Step

Use this document as the implementation baseline, then create a task-by-task execution checklist in the new services/interview-service workspace as soon as the folder archive and scaffold step is complete.