Polish, tests & single-image deploy (Session 5)

Deploy (Hugging Face Spaces, Docker SDK):
- Root Dockerfile builds a single image: stage 1 builds the React frontend,
stage 2 runs FastAPI serving the built assets plus the API under /api on
port 7860 (same origin, no CORS, one live URL).
- app/server.py: combined ASGI entrypoint mounting the API at /api and the
static frontend at / (guarded so tests import cleanly without a build).
- README front matter (sdk: docker, app_port: 7860) so a Space builds it
directly; .dockerignore for build-context hygiene.
- backend/.env.example and frontend/.env.example document CORS_ORIGINS,
DOCUASK_DB, and VITE_API_URL for split-hosting setups.

Polish:
- README rewritten for a recruiter: description, chat + dashboard
screenshots, feature list, API table, deploy steps, project structure.
- test_server.py verifies the API is reachable under /api in the combined
app.

Verified the combined server locally: /api/health, static index, and
/api/ask all serve correctly from one origin.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WN4QRr6dTE2W7hQ2SDnLmY

.dockerignore

@@ -0,0 +1,11 @@
+# Build context hygiene for the root (Hugging Face) image.
+**/node_modules
+**/dist
+**/__pycache__
+**/*.pyc
+**/.pytest_cache
+**/.venv
+**/*.db
+.git
+.github
+docs

.gitignore

@@ -17,6 +17,9 @@ dist-ssr/
 *.local
 .vite/
 
+# Built frontend staged into the backend image (see root Dockerfile)
+backend/static/
+
 # Env & secrets
 .env
 .env.*

Dockerfile

@@ -0,0 +1,34 @@
+# Single-image build for Hugging Face Spaces (Docker SDK).
+# Stage 1 builds the React frontend; stage 2 runs the FastAPI backend and
+# serves the built frontend from the same origin on port 7860.
+
+# ---- Stage 1: build the frontend ----
+FROM node:20-slim AS frontend
+WORKDIR /fe
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build            # outputs /fe/dist
+
+# ---- Stage 2: backend + static assets ----
+FROM python:3.11-slim
+WORKDIR /app
+
+# libgomp1 is required at runtime by faiss-cpu (OpenMP).
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY backend/ ./
+COPY --from=frontend /fe/dist ./static
+
+# HF Spaces expose port 7860. /tmp is writable regardless of the runtime user;
+# mount HF persistent storage and set DOCUASK_DB=/data/docuask.db to keep
+# telemetry across restarts.
+ENV DOCUASK_DB=/tmp/docuask.db
+EXPOSE 7860
+
+CMD ["uvicorn", "app.server:root", "--host", "0.0.0.0", "--port", "7860"]

PROJECT_SPEC.md

@@ -119,11 +119,17 @@ Goal: live URL + green CI + a README a recruiter can skim.
 - README: one-paragraph description, screenshot/GIF of the chat + dashboard,
   live demo link, run instructions, tech stack.
 
+> Note: this project deploys as a single-image **Hugging Face Space** (Docker),
+> which serves the frontend and API from one origin — replacing the split
+> Render/Vercel plan above.
+
 **Acceptance criteria**
 
-- [ ] CI badge is green on the default branch.
+- [x] CI badge is green on the default branch.
 - [ ] Live demo URL works end to end (upload → ask → feedback → dashboard).
-- [ ] README has a screenshot and the live link.
+      _Deploy config is ready (root `Dockerfile` + README front matter); awaiting
+      the owner creating the Hugging Face Space._
+- [x] README has a screenshot; live link is a placeholder until the Space is up.
 
 ## Guardrails
 

README.md

@@ -1,17 +1,46 @@
+---
+title: DocuAsk
+emoji: 📄
+colorFrom: green
+colorTo: gray
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
 # DocuAsk
 
 [![CI](https://github.com/Sriyansh-28/docuask/actions/workflows/ci.yml/badge.svg)](https://github.com/Sriyansh-28/docuask/actions/workflows/ci.yml)
 
-A full-stack **document Q&A web app**: upload a PDF (or paste text), ask
-questions in a chat box, and get answers with the **source passage** shown —
-plus a live feedback/telemetry dashboard.
+**DocuAsk** is a full-stack document Q&A web app. Upload a PDF (or paste text),
+ask questions in a chat box, and get answers with the **source passage** shown
+underneath — then rate each answer 👍/👎 and watch the usage metrics update on a
+live dashboard. It's a small, end-to-end product loop: a React front end, a
+FastAPI back end, a lightweight retrieval layer, and a SQLite telemetry layer,
+all runnable with one command and deployable as a single container.
+
+🔗 **Live demo:** _deploy to a Hugging Face Space (see [Deploy](#deploy-hugging-face-spaces)) and paste the URL here_ →
+`https://huggingface.co/spaces/<your-username>/docuask`
+
+## Screenshots
+
+| Chat — answer with source passage | Dashboard — live metrics |
+| :---: | :---: |
+| ![Chat view](docs/screenshots/chat.png) | ![Dashboard view](docs/screenshots/dashboard.png) |
 
-> **Status:** Session 4 — the feedback/telemetry layer is live. Every question
-> is logged to SQLite with its measured latency, answers carry 👍/👎 buttons,
-> and a `/#/dashboard` page shows total questions, median latency, and
-> thumbs-up rate live from the DB, plus a questions-over-time bar. Retrieval is
-> a lightweight BM25 + FAISS (TF-IDF) hybrid. Final polish/deploy is the last
-> session (see [`PROJECT_SPEC.md`](./PROJECT_SPEC.md)).
+## Features
+
+- **Upload & parse** — drag-and-drop a PDF or paste text; the backend extracts
+  (pypdf), chunks, and indexes it in memory. Encrypted / broken / non-PDF /
+  empty / oversize inputs all fail with a clear, friendly message.
+- **Chat with sources** — every answer shows the passage it was drawn from, so
+  the retrieval is transparent.
+- **Hybrid retrieval** — BM25 (`rank_bm25`) combined with a FAISS cosine search
+  over TF-IDF vectors; deliberately lightweight, no heavyweight model.
+- **Feedback & telemetry** — each question is logged to SQLite with its measured
+  latency; 👍/👎 feedback and a `/dashboard` page show total questions, median
+  latency, and thumbs-up rate live from the DB.
 
 ## Run it (one command)
 
@@ -19,8 +48,8 @@ plus a live feedback/telemetry dashboard.
 docker compose up --build
 ```
 
-Then open **http://localhost:5173** — you should see **"API status: ok"**
-pulled live from the backend at http://localhost:8000/health.
+Then open **http://localhost:5173**. The frontend calls the API through nginx,
+so there's nothing else to configure.
 
 ## Run without Docker (dev)
 
@@ -41,7 +70,7 @@ npm run dev                     # http://localhost:5173
 ```
 
 In dev the Vite server proxies `/api/*` to the backend, so no CORS setup is
-needed. In the Docker setup, nginx reverse-proxies `/api/` to the API service.
+needed.
 
 ## Tests
 
@@ -50,36 +79,83 @@ cd backend
 pytest
 ```
 
+The suite covers `/health`, upload success and every failure path, retrieval and
+`/ask`, `/feedback`, `/stats`, and the combined deploy entrypoint. CI runs it on
+every push.
+
+## API
+
+| Method | Path                | Purpose                                            |
+| ------ | ------------------- | -------------------------------------------------- |
+| GET    | `/health`           | Liveness probe.                                    |
+| POST   | `/documents`        | Ingest a PDF file or raw text → `document_id`.     |
+| GET    | `/documents/{id}`   | Document metadata.                                 |
+| POST   | `/ask`              | `{document_id, question}` → answer + source passage. |
+| POST   | `/feedback`         | Attach 👍/👎 (`up`/`down`) to an interaction.       |
+| GET    | `/stats`            | Totals, median latency, thumbs-up rate, over-time. |
+
+## Deploy (Hugging Face Spaces)
+
+The root [`Dockerfile`](./Dockerfile) builds a **single image** that serves the
+React frontend and the API from one origin (the API is mounted under `/api`), so
+you get one live URL with no CORS to configure.
+
+1. Create a new **Space** → **Docker** SDK (blank template).
+2. Push this repository to the Space (or connect the GitHub repo). The Space
+   reads the YAML front matter at the top of this README (`sdk: docker`,
+   `app_port: 7860`) and builds the root `Dockerfile`.
+3. Wait for the build; the app comes up at your Space URL. Paste that URL into
+   the **Live demo** link above.
+
+Telemetry uses `/tmp/docuask.db` by default (resets on restart). To persist it,
+add HF **persistent storage** and set `DOCUASK_DB=/data/docuask.db` in the
+Space's variables.
+
+> Prefer split hosting (e.g. static frontend + separate API)? Set
+> `VITE_API_URL` at frontend build time to the API origin and add that origin to
+> the backend's `CORS_ORIGINS`. See the `.env.example` files.
+
 ## Project structure
 
 ```
 docuask/
-  backend/            # FastAPI app, tests
-    app/main.py       # GET /health + CORS
-    tests/            # pytest suite
-  frontend/           # Vite + React + Tailwind
-    src/App.jsx       # calls /health and renders the status
-  docker-compose.yml  # brings both services up
-  .github/workflows/  # CI: pytest on every push
+  backend/              # FastAPI app + tests
+    app/
+      main.py           # API: /health, /documents, /ask, /feedback, /stats
+      parsing.py        # PDF/text extraction + chunking
+      retrieval.py      # BM25 + FAISS (TF-IDF) hybrid index
+      store.py          # in-memory document store
+      db.py             # SQLite interaction telemetry
+      server.py         # combined static + API entrypoint (deploy)
+    tests/              # pytest suite
+  frontend/             # Vite + React + Tailwind
+    src/
+      App.jsx           # layout + hash routing (Chat / Dashboard)
+      DocumentUploader.jsx, Chat.jsx, Dashboard.jsx
+  Dockerfile            # single-image build for Hugging Face Spaces
+  docker-compose.yml    # local: frontend + backend together
+  .github/workflows/    # CI: pytest + frontend build on every push
 ```
 
 ## Tech stack
 
 - **Frontend:** React + Vite + Tailwind CSS
 - **Backend:** FastAPI (Python)
+- **Retrieval:** BM25 + FAISS over TF-IDF
+- **Persistence:** SQLite (interaction telemetry)
 - **Tests:** pytest
-- **CI:** GitHub Actions (pytest on every push)
-- **Local orchestration:** Docker Compose
+- **CI:** GitHub Actions (pytest + build on every push)
+- **Deploy:** Docker (single-image Hugging Face Space); Docker Compose locally
 
 ## Roadmap
 
 See [`PROJECT_SPEC.md`](./PROJECT_SPEC.md) for the full plan:
 
 1. ✅ Skeleton end to end (health check wired browser → API)
-2. Upload & parse flow (PDF/text → chunked, indexed)
-3. Retrieval + chat loop (BM25 + FAISS, source passages)
-4. Data-collection & feedback layer (SQLite, 👍/👎, `/stats`, dashboard)
-5. Polish, tests, live deploy
+2. ✅ Upload & parse flow (PDF/text → chunked, indexed)
+3. ✅ Retrieval + chat loop (BM25 + FAISS, source passages)
+4. ✅ Data-collection & feedback layer (SQLite, 👍/👎, `/stats`, dashboard)
+5. ✅ Polish, tests, deploy (single-image Docker Space)
 
 ## License
 

backend/.env.example

@@ -0,0 +1,12 @@
+# Backend configuration (copy to .env or set in your host's dashboard).
+
+# Comma-separated list of allowed CORS origins. Only needed when the frontend
+# is served from a DIFFERENT origin than the API (split hosting). In the
+# single-image Hugging Face deploy the frontend is same-origin, so this can be
+# left unset.
+# CORS_ORIGINS=https://your-frontend.example.com
+
+# Path to the SQLite telemetry database. Defaults to ./docuask.db locally and
+# /tmp/docuask.db in the container image. Point at persistent storage
+# (e.g. /data/docuask.db) to keep interactions across restarts.
+# DOCUASK_DB=/data/docuask.db

backend/app/server.py

@@ -0,0 +1,31 @@
+"""Combined ASGI app for single-container deploys (Hugging Face Spaces).
+
+Serves the built frontend as static files and mounts the API under ``/api`` so
+the browser only ever talks to one origin (no CORS, one demo URL). The
+frontend's default API base is ``/api``, so no build-time config is needed.
+
+Local dev and docker-compose keep using ``app.main`` directly; this module is
+only the entrypoint for the single-image deployment.
+"""
+
+from __future__ import annotations
+
+import os
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from .main import app as api_app
+
+_STATIC_DIR = os.getenv(
+    "STATIC_DIR",
+    os.path.join(os.path.dirname(os.path.dirname(__file__)), "static"),
+)
+
+root = FastAPI(title="DocuAsk")
+root.mount("/api", api_app)
+
+# Mounted last so the API prefix wins; guarded so importing this module without
+# a built frontend (e.g. in tests) doesn't fail.
+if os.path.isdir(_STATIC_DIR):
+    root.mount("/", StaticFiles(directory=_STATIC_DIR, html=True), name="static")

backend/tests/test_server.py

@@ -0,0 +1,17 @@
+"""Tests for the combined deploy entrypoint (Session 5).
+
+Ensures the API is reachable under the /api prefix the frontend expects when
+both are served from one origin (Hugging Face Space).
+"""
+
+from fastapi.testclient import TestClient
+
+from app.server import root
+
+client = TestClient(root)
+
+
+def test_api_is_mounted_under_api_prefix():
+    response = client.get("/api/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}

frontend/.env.example

@@ -0,0 +1,7 @@
+# Frontend build-time configuration.
+
+# Base URL for the API. Leave UNSET for:
+#   - local dev (Vite proxies /api to the backend), and
+#   - the single-image Hugging Face deploy (API is same-origin under /api).
+# Set it only when hosting the frontend separately from the backend, e.g.:
+# VITE_API_URL=https://your-backend.example.com