104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
# 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.
|