How kevinyecs/pdf-knowledge-graph works
1. High-level split
- The repo is organized as two separate processes: a Python PDF extraction service and a React/Vite frontend.
- The backend turns a PDF into a graph-shaped JSON payload; the frontend renders and edits that graph.
- A key boundary is that graph edits do not modify the source document.
2. Backend service boundary
- The Python side runs as a FastAPI app launched with uvicorn from backend/app.py.
- Its main contract is a single extraction endpoint, used by the frontend through /api/*.
- The backend is responsible only for PDF parsing, entity/relation extraction, and JSON output, not UI state or persistence.
3. PDF ingestion layer
- backend/pdf_io.py wraps pdfplumber to read page text from PDFs.
- It also classifies pages with a tabular vs. prose heuristic, which determines which extraction path to use.
- This layer is the document boundary: it converts a file into page text and structural hints.
4. Extraction pipeline
- backend/extractor.py contains the core NLP and document-structure logic.
- Prose pages use spaCy for named entities and dependency parsing to derive subject–verb–object style relations.
- Tabular pages are parsed line-by-line into domain-like nodes such as headings, metrics, money values, and dates.
- The backend emits graph nodes, edges, and source-text references that the UI can later focus on.
5. Normalization and graph cleanup
- After extraction, the backend merges near-duplicate entities using rapidfuzz.
- Parallel edges are folded with weights, and weak isolated nodes are pruned.
- This step is important because the frontend receives a clean graph, not raw NLP output.
6. Frontend runtime and network boundary
- The frontend is a Vite + React + TypeScript app.
- In development, Vite proxies /api requests to the Python service on 127.0.0.1:8000, so the browser talks to one origin.
- src/lib/extract.ts is the network adapter that calls the backend and turns its response into frontend state.
7. Main UI composition
- src/App.tsx is the orchestration layer that wires together upload, fetch, selection, search, and edit state.
- The main visible subsystems are:
- Sidebar.tsx for upload, backend status, and search
- GraphView.tsx for the canvas graph
- TextPanel.tsx for read-only source text
- EntityNode.tsx for node rendering
- This makes the UI a graph editor with a separate source-document viewer.
8. Graph rendering and editing
- GraphView.tsx uses @xyflow/react to draw the node-link canvas.
- src/lib/layout.ts uses dagre to compute graph layout before rendering.
- The canvas supports node selection, drag-to-create edges, rename, and delete actions.
- These edits affect only the in-memory graph model in the frontend.
9. Search and focus behavior
- src/lib/search.ts ranks nodes for search, with the UI centering on the top hit and dimming non-matches.
- Selecting a node or edge updates the TextPanel to show the matching source sentences.
- This creates a one-way flow from graph interaction back to source text context, without changing the underlying PDF data.
10. Persistence and deployment shape
- There is no persistence layer in this repo: edited graphs are not saved to disk or a database.
- The app is designed for local, interactive use: backend service plus frontend dev server, or a static frontend build plus a separately running Python API.
- The bundled samples/ PDFs and the Hungarian walkthrough in docs/DOKUMENTACIO.md are reference inputs/documentation, not runtime dependencies.
Main entry points: App.tsx App shell · app.py API app · GraphView.tsx Graph view · extractor.py Extractor
Components 17
Python API
FastAPI PDF extraction service
React UI
Vite frontend for graph viewing and editing
- App shell · Coordinates upload, fetch, selection, search, and edit state.
src/App.tsx - API client · Calls the backend and converts responses into frontend state.
src/lib/extract.ts - Layout · Computes node placement before rendering the graph.
src/lib/layout.ts - Search · Ranks nodes for search and drives focus behavior.
src/lib/search.ts - Graph view · Renders the editable node-link graph and handles canvas interactions.
src/components/GraphView.tsx - Entity node · Renders individual graph nodes in the canvas.
src/components/EntityNode.tsx - Sidebar · Handles upload, backend status, and search controls.
src/components/Sidebar.tsx - Text panel · Shows matching source text for the selected graph item.
src/components/TextPanel.tsx - Main entry · Mounts the React application into the page.
src/main.tsx - Styles · Global styling for the frontend.
src/index.css - Vite config · Configures development and build-time behavior, including API proxying.
vite.config.ts
References
Sample PDFs and documentation
- Finance sample · Reference input used to demonstrate extraction behavior.
samples/finance.pdf - Rohini sample · Reference input used to demonstrate extraction behavior.
samples/rohini.pdf - Guide · Hungarian walkthrough of the system and usage.
docs/DOKUMENTACIO.md
Connections 21
- API app → PDF I/O: reads pages · The API entrypoint uses the PDF reader to ingest documents.
- API app → Extractor: extracts graph · The app hands parsed document content to the extraction pipeline.
- PDF I/O → Extractor: page text · Page text and page-type hints feed the NLP and structure extraction logic.
- Extractor → API app: JSON payload · The extractor returns graph data to the API layer for response serialization.
- App shell → API client: loads PDF · The app shell requests extraction results from the backend client.
- API client → API app: api call · The frontend talks to the Python service through the API boundary.
- App shell → Graph view: renders graph · The main app passes graph state into the canvas view.
- App shell → Sidebar: controls · The app wires upload, status, and search controls into the sidebar.
- App shell → Text panel: selection context · Selected nodes or edges drive the source-text panel.
- Graph view → Entity node: node UI · The canvas uses the node renderer for individual entities.
- Graph view → Layout: positions · Graph data is laid out before rendering.
- Sidebar → Search: search input · Sidebar search drives ranking and focus behavior.
- App shell → Search: focus state · The app uses search results to center the graph and dim non-matches.
- Graph view → Text panel: focus source · Graph selections update the source-text viewer.
- Vite config → API client: proxy /api · Development proxy routes API requests to the Python backend.
- Main entry → App shell: mounts · The entry point mounts the application shell.
- Main entry → Styles: loads styles · The entry point includes global styles for the UI.
- Guide → API app: documents · The guide describes the backend service and extraction flow.
- Guide → App shell: documents · The guide describes the frontend interaction model.
- Finance sample → API app: example input · Sample PDFs demonstrate the extraction service.
- Rohini sample → API app: example input · Sample PDFs demonstrate the extraction service.