docs/KNOWLEDGE_GRAPH.md

# Knowledge Graph - Link PDF Pages to Questions

## Overview

The Knowledge Graph feature allows you to visually link PDF pages to specific questions using an interactive node-based editor. Linked pages become accessible as revision notes.

## Features

- **Visual Node Editor** - Drag-and-drop interface using React Flow
- **Link PDF Pages** - Connect any PDF page to any question
- **Revision Notes Integration** - Linked pages appear as revision notes
- **Auto-Save** - Links are saved to the existing database structure
- **Bidirectional Access** - Access linked pages from questions and vice versa

## How to Use

### 1. Open Graph Editor

From the Question Entry page (`/question_entry_v2/<session_id>`):

1. Scroll to the "Generate PDF" section
2. Click the **"Link PDF Pages to Questions"** button
3. The graph editor opens in a new page

### 2. Understanding the Interface

```
┌─────────────────────────────────────────────────────────────┐
│  [← Back]  [Clear]  [Save & Link]                          │
├──────────┬──────────────────────────────────────────────────┤
│          │                                                  │
│  PDF     │              GRAPH CANVAS                        │
│  Pages   │                                                  │
│  Panel   │   [Question Nodes] ←─── [Page Nodes]            │
│          │                                                  │
│  [Page1] │                                                  │
│  [Page2] │                                                  │
│  [Page3] │                                                  │
│          │                                                  │
└──────────┴──────────────────────────────────────────────────┘
```

### 3. Create Links

1. **Drag a PDF page** from the left sidebar onto the canvas
2. **Drag from the page node** to a question node to create a link
3. **Repeat** for all pages you want to link
4. Click **"Save & Link"** to save

### 4. Access Linked Pages

After saving:

- Linked pages appear as revision notes for the connected questions
- Access them via the revision notes modal in Question Entry
- Pages are stored in the existing `images.note_json` and `images.note_filename` fields

## Node Types

### Question Node (Blue)
```
┌─────────────────────┐
│ ❓ Q12              │
│ 📗 Physics          │
│ 📁 Mechanics        │
│ ✅ Has Notes        │
└─────────────────────┘
```
- Shows question number, subject, chapter
- Green border indicates existing notes
- Connection point on the right

### Page Node (Purple)
```
┌─────────────────────┐
│ 📄 Page 5           │
│ ┌─────────────────┐ │
│ │   Page Image    │ │
│ └─────────────────┘ │
└─────────────────────┘
```
- Shows PDF page thumbnail
- Connection point on the left
- Drag from sidebar to create

## Data Structure

### Saved Link Format

```json
{
  "type": "linked_page",
  "source_page_id": 123,
  "source_page_number": 5,
  "source_filename": "upload_abc123.jpg",
  "linked_at": "2026-03-17T10:30:00",
  "original_note": null
}
```

### Database Schema

Links are stored in the existing `images` table:

| Column | Description |
|--------|-------------|
| `note_json` | JSON containing link data |
| `note_filename` | Reference to the linked page image |
| `session_id` | Session this belongs to |

## API Endpoints

### GET `/session/<session_id>/graph`
Open the graph editor for a session.

### POST `/session/graph/save`
Save graph links.

**Request:**
```json
{
  "session_id": "abc123",
  "links": [
    {
      "page_id": 5,
      "question_image_id": 10,
      "page_number": 5
    }
  ]
}
```

**Response:**
```json
{
  "success": true,
  "message": "Linked 1 pages to questions",
  "links_count": 1
}
```

### GET `/session/graph/load/<session_id>`
Load existing graph links.

### POST `/session/graph/delete/<session_id>`
Delete all graph links for a session.

## Workflow Example

### Scenario: Link difficult questions to reference pages

1. **Upload PDF** with questions and solutions
2. **Enter Question Entry** page
3. **Click "Link PDF Pages to Questions"**
4. **Drag solution page** (e.g., page 10) to Question 5
5. **Drag another page** (e.g., page 15) to Question 8
6. **Save & Link**
7. **Return to Question Entry**
8. **Click revision notes icon** on Question 5
9. **See linked solution page** as a revision note!

## Benefits

✅ **Visual Organization** - See all connections at a glance
✅ **Quick Reference** - Link solutions, formulas, diagrams
✅ **Study Aid** - Create custom revision materials
✅ **Flexible** - Link any page to any question
✅ **Persistent** - Saved to database, survives page reloads

## Tips & Tricks

### Best Practices

1. **Link solution pages** to their corresponding questions
2. **Create formula sheets** by linking reference pages
3. **Group related questions** by linking them to the same reference
4. **Add diagrams** from appendix pages to relevant questions

### Keyboard Shortcuts

- `Delete/Backspace` - Delete selected node or edge
- `Ctrl+C/V` - Copy/paste nodes (coming soon)
- `Mouse Wheel` - Zoom in/out
- `Right-click + Drag` - Pan canvas

### Performance Tips

- Keep graphs under 100 nodes for best performance
- Use the MiniMap to navigate large graphs
- Clear unused nodes before saving

## Troubleshooting

### Page not showing in sidebar
- Ensure PDF was uploaded and processed
- Check that images exist in the database
- Refresh the page

### Can't create connection
- Make sure you're dragging FROM page TO question
- Release mouse over the question node
- Check browser console for errors

### Links not saving
- Ensure you clicked "Save & Link"
- Check network tab for failed requests
- Verify session ownership

## Technical Details

### Built With

- **React Flow** - Node-based graph editor
- **Preact** - Lightweight React alternative
- **Flask** - Python backend
- **SQLite** - Database storage

### File Structure

```
Report-Generator/
├── templates/
│   ├── graph_editor.html      # React Flow editor
│   └── question_entry_v2.html # Entry point
├── graph_routes.py             # Backend routes
└── docs/
    └── KNOWLEDGE_GRAPH.md     # This file
```

## Future Enhancements

- [ ] Export graph as image/PDF
- [ ] Import/export graph data
- [ ] Multi-session graphs
- [ ] Collaborative editing
- [ ] Auto-suggest links based on content
- [ ] Graph templates
- [ ] Search and filter nodes

## Support

For issues or questions:
1. Check browser console for errors
2. Verify database integrity
3. Review this documentation
4. Report bugs with screenshots