PROJECT_SPEC.md

DocuAsk — Full-Stack Document Q&A Web App

Purpose (read first)

A customer-facing web app where a user uploads a PDF (or pastes text), asks questions in a chat box, and gets answers with the source passage shown. The retrieval backend is intentionally lightweight — the point of this project is the front-end product loop and user-facing data collection, not the RAG. Spend effort on the UI, error handling, and the feedback/telemetry layer.

Target reviewer: general software-engineering apprenticeship (React front-end, REST API, CI/CD, deployed live URL, product metrics).

Stack (fixed — do not substitute)

• Frontend: React + Vite + Tailwind CSS
• Backend: FastAPI (Python)
• Retrieval: BM25 + FAISS (keep minimal; a single in-memory index is fine)
• Persistence: SQLite (question/answer/latency/feedback log)
• Tests: pytest (backend)
• CI: GitHub Actions running pytest on every push
• Deploy: Docker Compose locally; frontend to Vercel/Netlify, backend to Render/Railway

Repository setup (Session 0)

Public GitHub repo named docuask under github.com/Sriyansh-28.

• git init, add a Python + Node .gitignore, MIT license, README.md.
• Structure:

docuask/
  backend/        # FastAPI app, retrieval, db, tests
  frontend/       # Vite React app
  docker-compose.yml
  .github/workflows/ci.yml
  README.md
  PROJECT_SPEC.md

• First commit: skeleton only. Push to the new remote before writing features.

Session 1 — Skeleton end to end

Goal: browser shows data fetched from the API.

• FastAPI app with GET /health returning {"status":"ok"}.
• Vite React app with one page that calls /health and renders the status.
• Docker Compose brings both up with one docker compose up.
• CORS configured so frontend can call backend in dev.

Acceptance criteria

• docker compose up starts both services with no errors.
• Opening the frontend URL shows "API status: ok" pulled live from the backend.
• Repo pushed; README has a one-line run instruction.

Session 2 — Upload & parse flow

Goal: user uploads a PDF; backend extracts and chunks the text.

• POST /documents accepts a PDF or raw text, extracts text (pypdf), splits into chunks, builds/stores the index in memory keyed by a document id.
• Frontend: drag-and-drop upload widget with loading and success states.
• Handle failures visibly: encrypted PDF, non-PDF file, empty/huge file → clear error message in the UI, no crash.

Acceptance criteria

• Uploading a normal PDF returns a document id and shows "ready" in the UI.
• Uploading a broken/encrypted PDF shows a friendly error, backend logs it.
• A pytest test covers the parse-failure path.

Session 3 — Retrieval + chat loop

Goal: the core question→answer experience.

• POST /ask takes {document_id, question}, runs BM25 + FAISS retrieval, returns the answer text plus the top source passage.
• Frontend: chat interface — question input, message history, each answer shows the source passage underneath.
• Show a loading indicator while /ask is in flight.

Acceptance criteria

• Asking a question about an uploaded doc returns a relevant passage.
• The source passage is visibly shown under each answer.
• Empty question or unknown document id is handled gracefully.

Session 4 — Data-collection & feedback layer (the score-lifting part)

Goal: turn this into a web-enabled system for data collection with product metrics.

• SQLite table interactions(id, document_id, question, answer, latency_ms, feedback, created_at).
• Every /ask call logs the row with measured latency_ms.
• 👍 / 👎 buttons on each answer → POST /feedback updates the row.
• GET /stats returns: total questions, median latency, thumbs-up rate.
• A small /dashboard page in the frontend reads /stats and shows 3 numbers + a simple bar of questions-over-time.

Acceptance criteria

• Each question persists with its real latency.
• Feedback buttons update the record and reflect in /stats.
• Dashboard page renders the three metrics live from the DB.

Session 5 — Polish, test, deploy

Goal: live URL + green CI + a README a recruiter can skim.

• Backend pytest suite covers /health, upload success + failure, /ask, /feedback.
• .github/workflows/ci.yml runs pytest on every push; badge in README.
• Deploy backend (Render/Railway) and frontend (Vercel/Netlify); wire the live API URL.
• README: one-paragraph description, screenshot/GIF of the chat + dashboard, live demo link, run instructions, tech stack.

Deployed as the single-image combined app (Dockerfile + app/server.py) on Railway — one container serving the React frontend and the FastAPI API under /api from one origin. (A Hugging Face Static Space + separate API is also supported; see the README.)

Acceptance criteria

• CI badge is green on the default branch.
• Live demo URL works end to end (upload → ask → feedback → dashboard) — verified against https://docuask-production-c732.up.railway.app.
• README has a screenshot and the live link.

Guardrails

• Keep retrieval simple; do not over-engineer the RAG. If a session is running long, cut retrieval sophistication, never the front-end or telemetry.
• Only report metrics you actually measured. No invented user counts.