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

{
  "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:

{
  "session_id": "abc123",
  "links": [
    {
      "page_id": 5,
      "question_image_id": 10,
      "page_number": 5
    }
  ]
}

Response:

{
  "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