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

Start the database (pgvector already provided — configure connection):

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

Set environment variables:

export OPENAI_API_KEY=sk-...
export APP_PASSWORD=changeme

Running Locally

Backend

cd backend
mvn spring-boot:run
# API available at http://localhost:8080

Frontend

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)

Open http://localhost:5173 in a browser.
Navigate to the Library section.
Upload a PDF textbook (any medical PDF, 10+ pages with diagrams).
Observe status changes: PENDING → PROCESSING → READY.
Pass criteria: Book appears as READY within 10 minutes.
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)

At least one book MUST be in READY state.
Navigate to the Topics section.
Select any topic from the list.
Click Generate Summary.
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.
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)

Navigate to the Chat section.
Start a new session (optionally tied to a topic).
Ask a specific clinical question answerable from the uploaded book.
Pass criteria:
- Response arrives within 30 seconds.
- Response cites a source book and page number.
Ask a follow-up question that references the previous answer (e.g., "Can you expand on the grading scale you mentioned?").
Pass criteria: The response is coherent and contextually connected to the prior turn.
Ask something completely outside the books' content.
Pass criteria: The system explicitly states it cannot find relevant information (not a hallucinated answer).
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):

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.

4.3 KiB Raw Blame History