How c-a-x/smartpaperai works
1. Overall shape
- This is a classic two-tier application: a Vue 3 + TypeScript frontend and a Spring Boot backend.
- The frontend is a presentation/orchestration layer; the backend owns all document processing, AI/RAG logic, persistence, and integration with external services.
2. Frontend boundary
- The frontend is organized by feature area under src/views/ and talks to the backend through src/api/*.
- src/utils/request.ts centralizes HTTP calls, auth headers, and error handling; src/utils/stream.ts supports streaming AI responses.
- src/router/ and src/layouts/MainLayout.vue define the user-facing navigation shell, while Pinia stores handle cross-page state such as auth.
3. Backend API boundary
- Incoming requests hit Spring MVC controllers in controller/ such as DocumentController, KnowledgeBaseController, RAGController, OpenAIController, TeachingPlanController, and AuthController.
- These controllers are thin entry points that delegate to services; they are the main boundary between HTTP/API concerns and business logic.
- GlobalExceptionHandler and SaTokenAuthFilter provide cross-cutting error and authentication handling.
4. Core domain subsystems
- The backend is split into domain services for documents, knowledge bases, chat/RAG, analysis, knowledge graphs, and teaching plans.
- DocumentService, KnowledgeBaseService, ChatService, RAGService, PaperAnalysisService, KnowledgeGraphBuilderService, and TeachingPlanService are the main orchestration points.
- The impl/ package contains the concrete implementations, indicating a service-interface boundary inside the backend.
5. Document ingestion pipeline
- Document upload is the entry point for the most complex workflow: files are stored, parsed, chunked, enriched with metadata, and then indexed for retrieval.
- FileStorageService handles uploaded files and the uploads/ directory shows local file persistence is part of the runtime model.
- DocumentParserService, GrobidMetadataService, and SmartChunkingService transform raw PDFs/DOCs/TXT into structured document chunks and metadata.
6. Asynchronous processing boundary
- Document processing is not purely synchronous: mq/DocumentProcessingProducer and mq/DocumentProcessingConsumer show a queued background job flow.
- DocumentTaskService and DocumentProcessingMessage indicate upload events are turned into processing tasks, likely to keep uploads responsive while heavier parsing/indexing runs asynchronously.
- RabbitMQConfig confirms RabbitMQ is the messaging boundary for this workflow.
7. Search and retrieval layer
- The repository uses Elasticsearch for document search and retrieval-oriented indexing, with DocumentESRepository, DocumentESService, and ElasticsearchIndexInitializer.
- The model/entity/DocumentES and Elasticsearch config classes suggest documents are denormalized into search documents separate from the relational model.
- DynamicRetrievalService, RerankService, and RAGService sit on top of this index to select relevant chunks for AI answers.
8. RAG and LLM integration
- The AI-facing subsystem is centered around ChatClientConfig, PromptTemplateConfig, and the prompt files under resources/prompts/.
- RAG flows combine retrieval from Elasticsearch plus optional graph context, then send prompts to the LLM through the chat client.
- GraphEnhancedRAGService and RAGConfiguration suggest a configurable retrieval-augmented generation pipeline with prompt templates and tunable retrieval parameters.
9. Knowledge graph subsystem
- The graph model is represented explicitly by model/graph/* nodes such as DocumentNode, ConceptNode, and AuthorNode.
- repository/graph/* provides persistence access for graph entities, while KnowledgeGraphBuilderService and ConceptExtractionService construct the graph from parsed documents.
- The frontend’s knowledge-graph views consume this model for visualization and exploration, so the graph store is a distinct read model rather than just a UI feature.
10. Persistence model
- Relational data is handled through MyBatis-style mappers in mapper/ and SQL scripts under resources/db/.
- Domain entities include users, documents, tags, knowledge bases, chat sessions/messages, document tasks, vectors, and teaching plans.
- MyMetaObjectHandler and the presence of separate DO/VO/DTO types show a deliberate boundary between database records, API payloads, and UI responses.
11. Caching and session/state
- RedisConfig indicates Redis is used as an infrastructure layer for ephemeral state such as cache, session, or task-related data.
- Authentication uses token-based access with Sa-Token support, and the frontend stores token/user info locally to attach on each request.
- This keeps interactive features like chat and multi-step document workflows resilient without relying only on request-scoped state.
12. Analysis and report generation
- The analysis/ controllers and services produce higher-level academic outputs: summaries, comparisons, innovation clustering, literature reviews, and teaching-plan generation.
- These features are template/LLM driven, using prompt resources plus structured DTO/VO contracts to return report-like results.
- The analysis layer is mostly read-heavy and generated-content oriented, separate from the core document storage and retrieval pipeline.
13. External integration points
- The backend integrates with Grobid for scholarly document parsing/metadata extraction, RabbitMQ for async processing, Elasticsearch for search, and likely a graph database for knowledge graph persistence.
- The frontend is a pure SPA that relies on the backend for all data and AI capabilities; deployment can place it behind Nginx with API proxying.
- These infrastructure dependencies are architecturally important because they define the main runtime boundaries and data flows.
14. Typical end-to-end flow
- A user uploads a paper in the frontend → backend stores the file → async processing parses/chunks/enriches it → metadata/search/graph records are written → the document becomes available in lists, search, graph views, and RAG chat.
- A chat or analysis request then goes from UI → controller → retrieval/prompting services → LLM response → streamed or structured response back to the client.
- In short, the system is built around one central domain object, the academic paper, with multiple read models layered on top: search, graph, chat context, and generated analysis.
Main entry points: index.ts Router · request.ts HTTP client · ChatClientConfig.java Infra config · DocumentService.java Domain services
Components 22
Frontend
Vue 3 single-page app for browsing documents, chat, analysis, knowledge graphs, and teaching plans.
- App shell · Root Vue application and global composition entry.
SmartPaperAi-frontend/src/App.vue - Main layout · Primary application frame and shared UI layout.
SmartPaperAi-frontend/src/layouts/MainLayout.vue - Router · Client-side navigation between feature views.
SmartPaperAi-frontend/src/router/index.ts - HTTP client · Shared request layer with auth headers and error handling.
SmartPaperAi-frontend/src/utils/request.ts - Stream utils · Helpers for streaming AI responses to the UI.
SmartPaperAi-frontend/src/utils/stream.ts - Auth store · Cross-page authentication and user session state.
SmartPaperAi-frontend/src/stores/auth.ts - Document views · Document list and detail screens for paper browsing.
SmartPaperAi-frontend/src/views/document/DocumentListView.vue - Knowledge views · Knowledge base list and detail screens.
SmartPaperAi-frontend/src/views/knowledge/KnowledgeListView.vue - Graph view · Knowledge graph exploration and visualization UI.
SmartPaperAi-frontend/src/views/knowledge-graph/KnowledgeGraphView.vue - Chat UI · Interactive chat experience for document and RAG questions.
SmartPaperAi-frontend/src/views/chat/ChatView.vue - RAG chat · Dedicated retrieval-augmented chat interface.
SmartPaperAi-frontend/src/views/rag/RagChatView.vue - Analysis views · Paper summary, comparison, literature review, and innovation clustering screens.
SmartPaperAi-frontend/src/views/analysis/PaperSummaryView.vue - Teaching views · Teaching plan list, edit, and detail interfaces.
SmartPaperAi-frontend/src/views/teaching/TeachingListView.vue
Backend
Spring Boot API and processing engine for documents, retrieval, AI, persistence, and integrations.
- Controllers · Spring MVC entry points for auth, documents, knowledge, chat, RAG, analysis, and teaching plans.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/controller/DocumentController.java - Domain services · Main service layer for document, knowledge base, chat, analysis, graph, and teaching workflows.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/service/DocumentService.java - Ingestion pipeline · Storage, parsing, metadata extraction, chunking, and task creation for uploaded papers.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/service/DocumentParserService.java - Async worker · RabbitMQ-backed producer/consumer flow for background document processing.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/mq/DocumentProcessingProducer.java - Search index · Document search and retrieval index plus index initialization.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/service/DocumentESService.java - RAG engine · Dynamic retrieval, reranking, prompt assembly, and chat response generation.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/service/RAGService.java - Knowledge graph · Concept/document graph extraction and persistence for graph-enhanced retrieval and visualization.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/service/KnowledgeGraphBuilderService.java - Persistence · MyBatis mappers and entity model for users, documents, tasks, chats, knowledge bases, tags, and plans.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/mapper/DocumentMapper.java - Infra config · Chat client, Grobid, Redis, RabbitMQ, Elasticsearch, file storage, token auth, and exception handling configuration.
SmartPaperAI-backend/src/main/java/com/GeekPaperAssistant/config/ChatClientConfig.java
Connections 32
- App shell → Main layout: uses · Application composes the shared navigation shell.
- Main layout → Router: hosts · Layout renders routed feature pages.
- Router → Document views: routes · Navigation exposes document screens.
- Router → Knowledge views: routes · Navigation exposes knowledge base screens.
- Router → Graph view: routes · Navigation exposes graph exploration.
- Router → Chat UI: routes · Navigation exposes chat screens.
- Router → RAG chat: routes · Navigation exposes RAG chat.
- Router → Analysis views: routes · Navigation exposes analysis reports.
- Router → Teaching views: routes · Navigation exposes teaching plan pages.
- Document views → HTTP client: calls · Document pages use shared API transport.
- Knowledge views → HTTP client: calls · Knowledge pages fetch data through the API client.
- Graph view → HTTP client: calls · Graph view loads backend graph data.
- Chat UI → Stream utils: streams · Chat UI consumes streamed responses.
- Chat UI → HTTP client: calls · Chat UI also uses API requests for session and history data.
- RAG chat → Stream utils: streams · RAG chat renders incremental model output.
- Analysis views → HTTP client: calls · Analysis pages request generated reports.
- Teaching views → HTTP client: calls · Teaching pages load and save plan data.
- Auth store → HTTP client: auths · Stored tokens are attached to outbound requests.
- Controllers → Domain services: delegates · Controllers forward business work to services.
- Domain services → Ingestion pipeline: orchestrates · Document and knowledge workflows start with ingestion.
- Ingestion pipeline → Async worker: enqueues · Heavy processing is handed off to queued jobs.
- Async worker → Persistence: updates · Background processing persists task and document state.
- Domain services → Search index: indexes · Services write and query the Elasticsearch read model.
- Domain services → RAG engine: uses · Chat and retrieval features are built on the RAG engine.
- RAG engine → Search index: retrieves · RAG pulls candidate chunks from the search index.
- RAG engine → Knowledge graph: augments · Graph context can enrich retrieval and prompting.
- Knowledge graph → Persistence: persists · Graph data is stored through repositories and mappers.
- Ingestion pipeline → Persistence: writes · Parsed documents, chunks, metadata, and tasks are persisted.
- Infra config → Controllers: cross-cuts · Auth and exception handling wrap API entry points.
- Infra config → Ingestion pipeline: supports · File storage, Grobid, and RabbitMQ enable ingestion.
- Infra config → Search index: supports · Elasticsearch client and index init support retrieval.
- Infra config → RAG engine: supports · Chat client and prompt configuration support generation.