# 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.