python-template/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is 学习助手 Pro (Learning Assistant Pro), an intelligent exam paper management and learning tracking system built with FastAPI (backend) and Vue 3 (frontend). The system specializes in PDF exam paper processing, automatic question extraction using AI/OCR, mistake management, and personalized learning with spaced repetition algorithms.

Core Features

• PDF Processing: High-speed PDF text extraction (0.01s/page) with 95%+ accuracy using hybrid text layer + OCR approach
• Question Extraction: AI-powered automatic question identification and extraction from exam papers
• Mistake Management: Ebbinghaus forgetting curve-based review system for mistake tracking
• Word Learning: SM-2 spaced repetition algorithm for English vocabulary learning
• Analytics: Comprehensive learning statistics and progress visualization

Development Commands

Quick Start

# Start both backend and frontend with provided script
./start.sh

# Check system status
./status.sh

# Stop all services
./stop.sh

Backend Development (Python/FastAPI)

cd backend

# Install dependencies
pip install -r requirements.txt

# Start development server (port 8888)
python main.py
# OR
uvicorn main:app --host 0.0.0.0 --port 8888 --reload

# View API documentation
# Open http://localhost:8888/docs in browser

Frontend Development (Vue 3/Vite)

cd frontend

# Install dependencies
npm install

# Start development server (auto-selects port, typically 3000-3002)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Database Operations

cd backend

# Initialize database with default data
python main.py  # Database auto-creates on first run

# Migrate database (if schema changes)
python migrate_db.py

Architecture Overview

Backend Architecture (FastAPI)

• Main Application: backend/main.py - Single-file FastAPI application with all API endpoints
• Database: SQLite with SQLAlchemy ORM (easily upgradeable to PostgreSQL)
• Authentication: JWT-based with bcrypt password hashing
• File Processing: Specialized PDF processing modules in backend/pdf_splitter_*.py
• Upload Storage: Local file storage in backend/uploads/ directory

Key Backend Components

PDF Processing Pipeline

The system uses a hybrid approach for PDF processing:

• Primary: Text layer extraction for maximum speed (0.01s/page)
• Fallback: OCR processing for scanned PDFs using EasyOCR
• Main Module: backend/pdf_splitter_hybrid.py - Intelligent PDF processor

Database Models

All models are defined in backend/main.py:

• User Management: User, UserWordProgress
• Word Learning: Word, spaced repetition with SM-2 algorithm
• Paper Management: Paper with metadata and file references
• Question Extraction: Question, QuestionCollection with auto-extraction support
• Mistake Tracking: Mistake, ReviewLog with Leitner box system

API Structure

• Authentication: /api/auth/* - JWT-based login/register
• Word Management: /api/words/* - CRUD and spaced repetition learning
• Paper Management: /api/papers/* - PDF upload and management
• Question Processing: /api/questions/*, /api/papers/{id}/split - AI extraction
• Mistake Review: /api/mistakes/* - Leitner-based review system
• Analytics: /api/dashboard, /api/stats - Learning statistics

Frontend Architecture (Vue 3)

• Framework: Vue 3 with Composition API
• UI Library: Element Plus for consistent design
• State Management: Pinia stores for auth and word data
• Routing: Vue Router with authentication guards
• Build Tool: Vite for fast development and building

Key Frontend Components

• Authentication: frontend/src/stores/auth.js - JWT token management
• Word Learning: frontend/src/stores/word.js - Spaced repetition logic
• Views: Major application pages in frontend/src/views/
  • MainDashboard.vue - Main learning hub
  • PaperViewer.vue - PDF viewing and interaction
  • Learning.vue - Word learning interface
  • MistakeReview.vue - Review session interface

Routing Structure

• / - Main dashboard (requires auth)
• /subjects/:subject - Subject-specific paper listing
• /papers/:id - Paper detail view
• /papers/:id/view - PDF viewer with annotation support
• /words - Vocabulary learning interface
• /review - Mistake review sessions

Development Guidelines

Backend Development

• Database Changes: Add new models to backend/main.py, run python migrate_db.py if needed
• New API Endpoints: Add to backend/main.py, follow existing patterns
• PDF Processing: Extend backend/pdf_splitter_hybrid.py for new extraction features
• Authentication: Use get_current_user() dependency for protected routes

Frontend Development

• New Views: Add to frontend/src/views/ and register in frontend/src/router/index.js
• State Management: Add new stores in frontend/src/stores/ following existing patterns
• API Calls: Use the existing API service pattern in stores
• Authentication: Route guards implemented in router, check authStore.isAuthenticated

File Upload and Storage

• Backend: Files stored in backend/uploads/{user_id}/
• PDF Processing: Temporary files cleaned up automatically
• Frontend: File upload through drag-and-drop or click-to-upload interfaces

Testing and Development

• Backend Testing: Use FastAPI's automatic docs at /docs for API testing
• Frontend Testing: Development server supports hot reload
• PDF Processing: Test files can be added to backend/test_*.py modules

Performance Considerations

PDF Processing

• The system achieves 2900x performance improvement through hybrid text/OCR approach
• Text layer extraction: 0.01s per page
• OCR fallback: Used only when text layer extraction fails
• Image extraction: Automatic correlation with question content

Database Optimization

• SQLite for development/small deployments
• Easy migration path to PostgreSQL for production
• Indexes on frequently queried fields (user_id, subject, etc.)

Frontend Performance

• Lazy loading of route components
• Efficient state management with Pinia
• Responsive design with mobile-first approach

Deployment

Development Environment

• Use ./start.sh for easy development setup
• Backend runs on port 8888, frontend auto-selects port (3000-3002)
• Hot reload enabled for both frontend and backend

Production Considerations

• Change SECRET_KEY in backend production
• Configure CORS origins for specific domains
• Set up proper file storage with backup
• Consider PostgreSQL for production database
• Configure HTTPS/reverse proxy with nginx

Key Files to Understand

Backend Core Files

• backend/main.py - Complete FastAPI application (1659 lines)
• backend/pdf_splitter_hybrid.py - PDF processing engine
• backend/requirements.txt - Python dependencies
• backend/initial_words.csv - Default English vocabulary data

Frontend Core Files

• frontend/src/App.vue - Main application component with global styles
• frontend/src/main.js - Application bootstrap
• frontend/src/router/index.js - Route definitions and auth guards
• frontend/src/stores/auth.js - Authentication state management
• frontend/src/views/MainDashboard.vue - Primary user interface

Utility Scripts

• start.sh - Development server startup script
• status.sh - System status checking script
• stop.sh - Service shutdown script

This system is designed for rapid development and deployment while maintaining high performance for PDF processing and excellent user experience for learning management.