plan

2026-03-31 15:42:49 +02:00
parent 3507ce27e5
commit dc0bcab36e
10 changed files with 1246 additions and 0 deletions
--- a/specs/001-neuro-rag-learning/plan.md
+++ b/specs/001-neuro-rag-learning/plan.md
@@ -0,0 +1,103 @@
+# 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.