interview-doctor-js AGENTS.md

Interview Doctor – Agent Instructions

Project Overview

Interview Doctor is an offline, AI-powered interview preparation assistant built with JavaScript, Foundry Local, and SQLite. It uses Retrieval-Augmented Generation (RAG) to generate tailored interview questions based on the user's CV/resume and job description.

Key constraint: This application runs 100% offline. Never introduce cloud dependencies, external API calls, or features that require internet connectivity.

Technology Stack

• Runtime: Node.js >= 20 (ES modules)
• AI: Foundry Local via foundry-local-sdk – native ChatClient for inference (no OpenAI shim)
• Database: SQLite via sql.js – pure JavaScript, no native compilation (TF-IDF vectors for RAG retrieval)
• PDF: pdf-parse for offline text extraction
• Web: Express.js server + single-file HTML frontend (no build step, no framework)
• Tests: Node.js built-in test runner (node:test + node:assert/strict)

Architecture

src/
├── config.js       → Central configuration (model, paths, chunk sizes)
├── chunker.js      → Text chunking + TF-IDF + cosine similarity
├── vectorStore.js  → SQLite-backed vector store for RAG
├── pdfParser.js    → PDF text extraction
├── chatEngine.js   → RAG orchestration + Foundry Local LLM integration
├── prompts.js      → System prompts (full + compact variants)
├── server.js       → Express web server + REST/SSE API
└── ingest.js       → Document ingestion script

Coding Conventions

• ES modules throughout (import/export, "type": "module" in package.json)
• No TypeScript — plain JavaScript for simplicity and zero build step
• Single-file frontend — public/index.html contains all HTML, CSS, and JS inline
• No frameworks on the frontend — vanilla JavaScript, no React/Vue/etc.
• Parameterized queries for all SQLite operations (use ? placeholders with arrays, never string concatenation)
• Async VectorStore — use await VectorStore.create(dbPath) factory method (sql.js is async for init)
• Path sanitization — all file operations validate paths stay within expected directories
• Error handling — Express routes catch and log errors, return appropriate HTTP status codes