feat/response schemas

[DanielPopoola]

Description

During a review of the codebase, several endpoints were identified as returning untyped raw dicts with no declared response schema. This meant Swagger documented data as Any across those endpoints, giving the frontend team no contract to work against. This PR adds typed Pydantic response schemas for all affected endpoints and wires them into the route decorators via response_model=APIResponse[T] so Swagger correctly documents the full response envelope including the data field.

Type of Change

• feat — New feature
• refactor — Code refactoring (no functional change)

Related Issue

Closes #

Changes Made

• Extended app/schemas/dashboard.py with CompletedInterviewItem, ScheduledInterviewItem, DashboardLiveInterviewItem, DashboardOverviewResponse
• Extended app/schemas/calendar.py with CalendarUserItem, AvailabilitySlot
• Extended app/schemas/candidate.py with CandidateListItem
• Extended app/schemas/interview.py with InterviewSummaryDetailResponse, InterviewSessionStatusResponse, ScorecardSection, InterviewScorecardResponse, CandidateProfileDetail, InterviewProfileDetail, InterviewProfileResponse, InterviewConfirmResponse, TranscriptStopResponse, CriteriaUpdateResponse, ContextUpdateResponse, AIConfigUpdateResponse, RejoinSessionResponse
• Updated app/services/dashboard.py — get_completed() and get_schedule() now return typed lists instead of list[dict]
• Updated app/services/interview.py — all affected service methods now return typed Pydantic models instead of raw dicts
• Updated app/api/v1/routes/dashboard.py — added response_model=APIResponse[T] to all endpoints
• Updated app/api/v1/routes/calendar.py — added response_model=APIResponse[T] to all endpoints
• Updated app/api/v1/routes/candidates.py — added response_model=APIResponse[T] to all endpoints
• Updated app/api/v1/routes/interviews.py — added response_model=APIResponse[T] to all affected endpoints
• Added tests/test_schemas.py — smoke tests validating every new schema against real-shaped data

Proof of Work

API Response / Screenshots

// Swagger UI now documents data field correctly for all affected endpoints
// Example — GET /api/v1/dashboard/completed
// Status: 200 OK
// {
//   "success": true,
//   "message": "Completed sessions retrieved successfully",
//   "data": [
//     {
//       "interview_id": "...",
//       "candidate_name": "Jane Doe",
//       "role": "Backend Engineer",
//       "score": 85,
//       "completed_at": "2026-05-30T10:00:00"
//     }
//   ],
//   "meta": null
// }

Test Cases

• test_completed_interview_item
• test_scheduled_interview_item
• test_dashboard_live_interview_item
• test_calendar_user_item
• test_availability_slot
• test_candidate_list_item
• test_interview_summary_detail_response
• test_scorecard_section_and_response
• test_interview_profile_response
• test_interview_confirm_response
• test_criteria_update_response
• test_context_update_response
• test_ai_config_update_response
• test_transcript_stop_response
• test_session_status_response
• test_rejoin_session_response

Test output

# uv run pytest tests/test_schemas.py -v
tests/test_schemas.py::test_completed_interview_item PASSED                                                                          [  6%]
tests/test_schemas.py::test_scheduled_interview_item PASSED                                                                          [ 12%]
tests/test_schemas.py::test_dashboard_live_interview_item PASSED                                                                     [ 18%]
tests/test_schemas.py::test_calendar_user_item PASSED                                                                                [ 25%]
tests/test_schemas.py::test_availability_slot PASSED                                                                                 [ 31%]
tests/test_schemas.py::test_candidate_list_item PASSED                                                                               [ 37%]
tests/test_schemas.py::test_interview_summary_detail_response PASSED                                                                 [ 43%]
tests/test_schemas.py::test_scorecard_section_and_response PASSED                                                                    [ 50%]
tests/test_schemas.py::test_interview_profile_response PASSED                                                                        [ 56%]
tests/test_schemas.py::test_interview_confirm_response PASSED                                                                        [ 62%]
tests/test_schemas.py::test_criteria_update_response PASSED                                                                          [ 68%]
tests/test_schemas.py::test_context_update_response PASSED                                                                           [ 75%]
tests/test_schemas.py::test_ai_config_update_response PASSED                                                                         [ 81%]
tests/test_schemas.py::test_transcript_stop_response PASSED                                                                          [ 87%]
tests/test_schemas.py::test_session_status_response PASSED                                                                           [ 93%]
tests/test_schemas.py::test_rejoin_session_response PASSED                                                                           [100%]

============================================================ 16 passed in 5.41s ===========================================================

Checklist

• My branch follows the naming convention (feat/response-schemas)
• My commits follow Conventional Commits
• I have added meaningful tests that cover success and failure paths
• All new and existing tests pass locally (uv run pytest)
• I have included proof of work (JSON responses or screenshots)
• I have updated documentation if needed
• My code follows the project's style guidelines

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 3a55ab74-5aa5-4986-8386-d5b66858e6c2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/response-schemas

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}