plan

specs/001-neuro-rag-learning/quickstart.md

@@ -0,0 +1,142 @@
+# Quickstart: Neurosurgeon RAG Learning Platform
+
+**Branch**: `001-neuro-rag-learning`
+**Date**: 2026-03-31
+
+This guide covers how to run the full stack locally and validate each user story manually
+(per Principle V — POC Validation Gate).
+
+---
+
+## Prerequisites
+
+| Tool | Version | Notes |
+|------|---------|-------|
+| Java | 21+ | Check: `java -version` |
+| Maven | 3.9+ | Check: `mvn -version` |
+| Node.js | 20+ | Check: `node -version` |
+| Docker + Compose | any recent | PostgreSQL with pgvector is provided via Docker |
+| PostgreSQL + pgvector | provided | See environment setup below |
+
+---
+
+## Environment Setup
+
+1. **Start the database** (pgvector already provided — configure connection):
+
+   ```properties
+   # backend/src/main/resources/application.properties
+   spring.datasource.url=jdbc:postgresql://localhost:5432/aiteacher
+   spring.datasource.username=aiteacher
+   spring.datasource.password=<your-password>
+
+   # Spring AI — vector store
+   spring.ai.vectorstore.pgvector.dimensions=1536
+   spring.ai.vectorstore.pgvector.distance-type=COSINE_DISTANCE
+
+   # Spring AI — LLM provider (example: OpenAI)
+   spring.ai.openai.api-key=${OPENAI_API_KEY}
+   spring.ai.openai.chat.options.model=gpt-4o
+   spring.ai.openai.embedding.options.model=text-embedding-3-small
+
+   # Shared password auth
+   spring.security.user.name=neurosurgeon
+   spring.security.user.password=${APP_PASSWORD}
+   ```
+
+2. **Set environment variables**:
+
+   ```bash
+   export OPENAI_API_KEY=sk-...
+   export APP_PASSWORD=changeme
+   ```
+
+---
+
+## Running Locally
+
+### Backend
+
+```bash
+cd backend
+mvn spring-boot:run
+# API available at http://localhost:8080
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev
+# UI available at http://localhost:5173
+```
+
+---
+
+## Smoke Tests (Principle V Validation)
+
+Run these after the full stack is up to confirm each user story works end-to-end.
+
+### Smoke Test 1 — Book Upload & Embedding (US1 / P1)
+
+1. Open `http://localhost:5173` in a browser.
+2. Navigate to the **Library** section.
+3. Upload a PDF textbook (any medical PDF, 10+ pages with diagrams).
+4. Observe status changes: `PENDING` → `PROCESSING` → `READY`.
+5. **Pass criteria**: Book appears as `READY` within 10 minutes.
+6. **Diagram check**: Ask a topic question in Smoke Test 2 that references a diagram
+   caption from the book — confirm it surfaces.
+
+### Smoke Test 2 — Topic Summary (US2 / P2)
+
+1. At least one book MUST be in `READY` state.
+2. Navigate to the **Topics** section.
+3. Select any topic from the list.
+4. Click **Generate Summary**.
+5. **Pass criteria**:
+   - Summary appears within 30 seconds.
+   - At least one source citation is shown with a book title and page number.
+   - The summary content is visibly related to the selected topic.
+6. **No-source check**: Select a topic completely unrelated to your uploaded book.
+   Confirm the system responds with a clear "no relevant content found" message rather
+   than a hallucinated answer.
+
+### Smoke Test 3 — Knowledge Chat (US3 / P3)
+
+1. Navigate to the **Chat** section.
+2. Start a new session (optionally tied to a topic).
+3. Ask a specific clinical question answerable from the uploaded book.
+4. **Pass criteria**:
+   - Response arrives within 30 seconds.
+   - Response cites a source book and page number.
+5. Ask a follow-up question that references the previous answer
+   (e.g., "Can you expand on the grading scale you mentioned?").
+6. **Pass criteria**: The response is coherent and contextually connected to the prior turn.
+7. Ask something completely outside the books' content.
+8. **Pass criteria**: The system explicitly states it cannot find relevant information
+   (not a hallucinated answer).
+9. Use **Clear conversation** and verify the session resets.
+
+---
+
+## README Architecture Requirement (Principle IV)
+
+The `README.md` at the repo root MUST contain at minimum this system-context diagram
+(update as the architecture evolves):
+
+```mermaid
+graph TD
+    User["Neurosurgeon (Browser)"]
+    FE["Frontend\nVue.js 3 / Vite\n:5173"]
+    BE["Backend\nSpring Boot 4 / Spring AI\n:8080"]
+    DB["PostgreSQL + pgvector\n(provided)"]
+    LLM["LLM Provider\n(OpenAI / configurable)"]
+
+    User -->|HTTP| FE
+    FE -->|REST /api/v1/...| BE
+    BE -->|JDBC / pgvector| DB
+    BE -->|Embedding + Chat API| LLM
+```
+
+Copy this diagram into `README.md` to satisfy Principle IV before the PR is merged.