# Implementation Plan: Neurosurgeon RAG Learning Platform

**Branch**: `001-neuro-rag-learning` | **Date**: 2026-03-31 | **Spec**: [spec.md](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)

```text
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)

```text
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.