Phase 0: reconcile docs to live code + remove dead code #6
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,133 @@ | ||
| # Interview Lab — Thorough Fix Plan | ||
|
|
||
| > Audited 2026-07-19. A sequenced, merge-ready plan. Each phase: **goal → files → changes → verification**. | ||
| > Phases are independently shippable; **Phase 0 must land first**. | ||
|
|
||
| --- | ||
|
|
||
| ## Phase 0 — Reconcile Reality & Delete Dead Code | ||
| *Why first: docs/architecture are wrong. Fix the map before the journey.* | ||
|
|
||
| ### 0.1 Documentation truth-up | ||
| **Files:** `AGENTS.md`, `README.md`, `REDESIGN-PLAN.md`, `REMEDIATION_PLAN.md`, `docs/architecture.md` | ||
| - Rewrite AGENTS.md "Design System" section: replace *"Ethereal Glass / OLED black / sky `#007EFF`"* with the live **"Field Manual" light theme** (`#FAFAF7` bg, `#FF6B35` accent, `FieldCard`/`FieldButton`). | ||
| - README Tech Stack: change `UI` row to "Tailwind v4 + Field Manual design system"; fix `Export` row ("pdfkit" → "pdfkit + manual PDF builder" or remove pdfkit after Phase 3). | ||
|
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Resolve the PDF implementation contradiction. Line [14] permits documenting “pdfkit + manual PDF builder,” while Lines [66-68] plan to replace the hand-rolled builder with pdfkit. State one final implementation in the README plan—preferably Also applies to: 66-68 🤖 Prompt for AI Agents |
||
| - `REMEDIATION_PLAN.md`: delete false claim that `downloads/[id]/route.ts` is 879 lines (it's 53). | ||
| - Mark `REDESIGN-PLAN.md` as **superseded** (glass redesign was reverted) — or delete it. | ||
|
|
||
| ### 0.2 Delete dead code | ||
| | File | Reason | | ||
| |------|--------| | ||
| | `src/lib/browser-llm-integration.ts` (338 lines) | Not imported anywhere; fake rule-based AI | | ||
| | `src/components/interview-lab/UpgradeModal.tsx` | Stub, no-op | | ||
| | `src/components/interview-lab/SubscriptionBanner.tsx` | Stub, no-op | | ||
| | `src/lib/pricing.ts` (tier config) — *optional* | Only powers stubs; keep if PricingPage ever real | | ||
|
Comment on lines
+19
to
+24
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Add the required blank line before the table.
🧰 Tools🪛 markdownlint-cli2 (0.23.0)[warning] 19-19: Tables should be surrounded by blank lines (MD058, blanks-around-tables) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||
|
|
||
| **Verify:** `grep -r "browser-llm-integration\|UpgradeModal\|SubscriptionBanner" src` → no results; `bun run build` passes. | ||
|
Comment on lines
+21
to
+26
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win Align the pricing cleanup with the stated Phase 0 objective. The PR objective says four files are removed, including 🤖 Prompt for AI Agents |
||
|
|
||
| --- | ||
|
|
||
| ## Phase 1 — SOLID: AI Layer Refactor (SRP + OCP + DIP) | ||
| *Highest leverage: 4 routes share ~75-line duplicated JSON-extract loop, each calls the SDK directly.* | ||
|
|
||
| ### 1.1 `src/lib/ai/client.ts` — AIProvider abstraction (DIP) | ||
| ```ts | ||
| export interface AIProvider { | ||
| complete(system: string, user: string, opts?: { schema?: ZodSchema; signal?: AbortSignal }): Promise<unknown>; | ||
| } | ||
| export class ZAIProvider implements AIProvider { /* timeout 30s, abort, retry-once */ } | ||
| export const ai: AIProvider = new ZAIProvider(); | ||
| ``` | ||
| - Add `AbortSignal.timeout(30000)` + `try/catch` around `ZAI.create().chat.completions.create`. | ||
|
|
||
| ### 1.2 `src/lib/ai/handlers.ts` — `createAIHandler` factory (OCP) | ||
| ```ts | ||
| export function createAIHandler<T>(buildPrompt, schema: ZodSchema<T>) { | ||
| return async (req) => { /* auth → call ai.complete with schema → validate → return */ }; | ||
| } | ||
| ``` | ||
| - Centralize `extractJsonArray`/`extractJsonObject` parsing into tested util `src/lib/ai/json.ts`. | ||
|
|
||
| ### 1.3 Split routes | ||
| - `src/lib/ai/coach.ts`, `resume.ts`, `cover-letter.ts`, `assessment.ts` — each exports `buildPrompt()` + a zod `schema`. | ||
| - Refactor `src/app/api/ai/{coach,resume-review,cover-letter,assessment-score}/route.ts` to ~15 lines each calling `createAIHandler`. | ||
|
|
||
| ### 1.4 Add zod schemas | ||
| - `src/lib/ai/schemas.ts`: `CoachFeedbackSchema`, `ResumeReviewSchema`, `CoverLetterSchema`, `AssessmentScoreSchema` (replaces runtime `as` casts). | ||
|
|
||
| **Verify:** `__tests__/ai/client.test.ts` (mock `z-ai-web-dev-sdk`), `handlers.test.ts` (valid + malformed JSON → 500), `bun run test`. | ||
|
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '\n== Relevant files ==\n'
git ls-files 'FIX-PLAN.md' 'src/app/api/ai/coach/route.ts' '__tests__/ai/client.test.ts' 'handlers.test.ts'
printf '\n== FIX-PLAN.md excerpt ==\n'
nl -ba FIX-PLAN.md | sed -n '45,70p'
printf '\n== route.ts excerpt ==\n'
nl -ba src/app/api/ai/coach/route.ts | sed -n '1,220p'
printf '\n== Search for JSON parsing / fallback / HTTP 500 ==\n'
rg -n "JSON.parse|fallback feedback|return NextResponse\.json|status:\s*500|malformed|coach" src __tests__ FIX-PLAN.mdRepository: projectamazonph/Interview-lab Length of output: 298 🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '\n== FIX-PLAN.md excerpt ==\n'
sed -n '45,70p' FIX-PLAN.md | cat -n
printf '\n== route.ts excerpt ==\n'
sed -n '1,220p' src/app/api/ai/coach/route.ts | cat -n
printf '\n== Search for related tests and behavior ==\n'
rg -n "JSON.parse|fallback feedback|return NextResponse\.json|status:\s*500|malformed|coach" src __tests__ FIX-PLAN.md || true
printf '\n== Find test files ==\n'
fd -a 'client.test.ts|handlers.test.ts' . || trueRepository: projectamazonph/Interview-lab Length of output: 42809 Preserve the AI coach malformed-response contract. 🤖 Prompt for AI Agents |
||
|
|
||
| --- | ||
|
|
||
| ## Phase 2 — SOLID: Export Layer (SRP) | ||
| ### 2.1 `src/lib/export/docx.ts` | ||
| - Move `generateDocx` out of `export/route.ts` into its own module. | ||
|
|
||
| ### 2.2 `src/lib/export/pdf.ts` — replace hand-rolled byte builder | ||
| - Use already-installed `pdfkit` (currently unused). Fixes **silent truncation** (`if (y < 50) break`) by paginating. | ||
| - Add `content` size guard (reject > 50k chars) to prevent abuse. | ||
|
|
||
| ### 2.3 `src/app/api/export/route.ts` | ||
| - Becomes ~12 lines: auth → dispatch to `docx.ts` / `pdf.ts`. | ||
|
|
||
| **Verify:** `export.test.ts` generates real .docx/.pdf, asserts multi-page content isn't truncated. | ||
|
|
||
| --- | ||
|
|
||
| ## Phase 3 — SOLID: Entitlement Honesty (LSP) | ||
| ### 3.1 `src/lib/subscription/entitlement.ts` | ||
| ```ts | ||
| export interface EntitlementService { canAccess(feature): boolean; tier: string; } | ||
| export class FreeEntitlement implements EntitlementService { canAccess() { return true; } } | ||
| ``` | ||
| - `subscription-guard.ts` returns real interface; `use-subscription.ts` returns `FreeEntitlement` honestly (remove fake `-1`/no-op that *implies* gating). | ||
|
|
||
| **Verify:** `subscription.test.ts`. | ||
|
|
||
| --- | ||
|
|
||
| ## Phase 4 — Component Decomposition (SRP) | ||
| ### 4.1 `MockInterview.tsx` (618 →) | ||
| `src/components/interview-lab/mock-interview/{Setup,ActiveSession,Complete,useInterview}.tsx` | ||
|
|
||
| ### 4.2 Standardize error/empty states | ||
| - `ResumeLab` raw red `<div>` → `Alert` component (already built in `ui/`). | ||
| - Add skeletons to `MockInterview`/`ResumeLab` to match `DashboardView`. | ||
|
|
||
| ### 4.3 A11y fix | ||
| - `QuestionBank`: remove nested interactive (inner "Practice" button inside `role="button"` div) → make card a real `<article>` with a separate button. | ||
|
|
||
| **Verify:** `bun run lint`, component render tests. | ||
|
|
||
| --- | ||
|
|
||
| ## Phase 5 — Infra & Correctness | ||
| ### 5.1 Rate limiter (`middleware.ts`) | ||
| - Replace in-memory `Map` with **Upstash Redis** (`@upstash/ratelimit`) so it works across Vercel serverless. | ||
|
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: sed -n '90,120p' FIX-PLAN.mdRepository: projectamazonph/Interview-lab Length of output: 1324 🏁 Script executed: rg -n "Upstash|ratelimit|dependency decision|50-line|custom solution|existing dependency|Vercel serverless|rate limiter" FIX-PLAN.md README.md docs .github . 2>/dev/nullRepository: projectamazonph/Interview-lab Length of output: 781 Document the rate-limiter dependency choice. Add a short rationale for choosing 🤖 Prompt for AI AgentsSource: Coding guidelines |
||
| - Trust `x-forwarded-for` only behind Vercel proxy; add `x-vercel-ip` fallback. | ||
|
|
||
| ### 5.2 Font drift (`globals.css`) | ||
| - `JetBrains Mono`/`Inter` declared but unused → align to Space Grotesk + Plus Jakarta Sans (per spec) or update spec. | ||
|
|
||
| ### 5.3 `db.ts` | ||
| - Gate `log: ['query']` behind explicit `LOG_QUERIES=1` env (confirm off in prod). | ||
|
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win Document Specify the documentation location, expected default, and production-safe value for 🤖 Prompt for AI AgentsSource: Coding guidelines |
||
|
|
||
| --- | ||
|
|
||
| ## Effort & Sequencing | ||
|
|
||
| | Phase | Work | Est. | Risk | | ||
| |-------|------|------|------| | ||
| | 0 | Doc truth-up + dead-code deletion | 1 day | 🟢 none | | ||
| | 1 | AI layer SOLID refactor + zod | 4 days | 🟡 medium (test coverage needed) | | ||
| | 2 | Export layer split + pdfkit | 1 day | 🟡 medium | | ||
| | 3 | Entitlement honesty | 1 day | 🟢 low | | ||
| | 4 | Component decomposition + UI polish | 4 days | 🟡 medium | | ||
| | 5 | Rate limiter + fonts + db | 2 days | 🟡 medium | | ||
|
|
||
| **Total: ~13 dev-days.** Phases are independently shippable; Phase 0 must land first. | ||
|
|
||
| --- | ||
|
|
||
| ## Suggested first PR | ||
| **"Phase 0: Reconcile docs & remove dead code"** — smallest diff, zero behavioral risk, unblocks everything. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use a non-future audit date.
Line [3] says
Audited 2026-07-19, but the current date is July 18, 2026. Use the actual audit date to avoid claiming verification occurred tomorrow.🤖 Prompt for AI Agents