Implementation Plan: Neurosurgeon RAG Learning Platform

Branch: 001-neuro-rag-learning | Date: 2026-03-31 | Spec: spec.md Input: Feature specification from /specs/001-neuro-rag-learning/spec.md

Summary

Build a web application for neurosurgeons to upload medical textbooks (PDF), have them precisely embedded (text + diagram captions) into a pgvector store, then select from a predefined topic list to receive an AI-generated cross-book summary, and engage in a grounded RAG chat. Monorepo: Vue.js 3 frontend + Spring Boot 4 / Spring AI backend + PostgreSQL with pgvector.

Technical Context

Language/Version: Java 21 (backend), TypeScript / Node 20 (frontend) Primary Dependencies:

Backend: Spring Boot 4.0.5, Spring AI 1.1.4 (BOM), Spring Security, spring-ai-pdf-document-reader, Spring Data JPA, Flyway
Frontend: Vue.js 3, Vite, Pinia, Vue Router, Axios Storage: PostgreSQL 16 with pgvector extension (provided externally) Testing: JUnit 5 + Spring Boot Test (backend); Vitest + Vue Test Utils (frontend) Target Platform: Linux server / Docker-compose local dev Project Type: Web application — monorepo with backend/ and frontend/ at repo root Performance Goals:
PDF processing: < 10 min per 500-page textbook (SC-001)
Topic summary generation: < 30 s (SC-002) Constraints: POC scale (< 10 concurrent users); shared-password auth (no per-user accounts) Scale/Scope: Single shared book library; HTTP Basic with single in-memory user

Constitution Check

GATE: Must pass before Phase 0 research. Re-checked after Phase 1 design.

Principle	Status	Notes
I. KISS	✅ PASS	Two deployable units only (backend + frontend). No microservices. Shared library — no per-user isolation complexity.
II. Easy to Change	✅ PASS	Spring AI abstracts the LLM provider behind `ChatClient` / `EmbeddingModel` interfaces — swappable. PDF parser isolated in a service class.
III. Web-First Architecture	✅ PASS	REST API (`/api/v1/…`) backend; Vue.js SPA frontend communicating via API only.
IV. Documentation as Architecture	⚠ PENDING	README.md with Mermaid system-context diagram MUST be created in this PR. See quickstart.md.
V. POC Validation Gate	✅ PASS	All 3 user stories have defined manual smoke tests in spec.md.

Project Structure

Documentation (this feature)

specs/001-neuro-rag-learning/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
│   ├── books-api.md
│   ├── topics-api.md
│   └── chat-api.md
└── tasks.md             # Phase 2 output (/speckit.tasks — NOT created here)

Source Code (repository root)

backend/
├── src/
│   ├── main/
│   │   ├── java/com/aiteacher/
│   │   │   ├── book/           # Book upload, processing, embedding
│   │   │   ├── topic/          # Topic list and summary generation
│   │   │   ├── chat/           # Chat session and RAG chat
│   │   │   ├── config/         # Spring AI, Security, Web config
│   │   │   └── AiTeacherApplication.java
│   │   └── resources/
│   │       ├── application.properties
│   │       └── topics.json     # Predefined topic list (config file)
│   └── test/
│       └── java/com/aiteacher/
├── pom.xml
└── Dockerfile

frontend/
├── src/
│   ├── components/
│   ├── views/           # UploadView, TopicsView, ChatView
│   ├── stores/          # Pinia: bookStore, topicStore, chatStore
│   ├── services/        # api.ts — Axios wrapper
│   ├── router/
│   └── main.ts
├── index.html
├── vite.config.ts
├── package.json
└── Dockerfile

README.md                # Architecture + Mermaid diagrams (required by Principle IV)
docker-compose.yml       # Local dev: backend + frontend + postgres

Structure Decision: Web application layout (Option 2). Two deployable units at repo root (backend/, frontend/). No third project. Internal packages organised by domain slice (book / topic / chat) rather than layer, so each slice is self-contained and easy to change (Principle II).

Complexity Tracking

No Constitution violations requiring justification.

4.5 KiB Raw Blame History