# kevinyecs/pdf-knowledge-graph architecture

> Architecture diagram of the GitHub repository kevinyecs/pdf-knowledge-graph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kevinyecs/pdf-knowledge-graph
- Repository: https://github.com/kevinyecs/pdf-knowledge-graph

## Overview

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: [`src/App.tsx`](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/App.tsx) (App shell), [`backend/app.py`](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/backend/app.py) (API app), [`src/components/GraphView.tsx`](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/GraphView.tsx) (Graph view), [`backend/extractor.py`](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/backend/extractor.py) (Extractor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python API"]
  node_backend_app["API app<br/>FastAPI entrypoint<br/>[app.py]"]
  node_backend_pdf_io["PDF I/O<br/>pdfplumber adapter<br/>[pdf_io.py]"]
  node_backend_extractor{{"Extractor<br/>NLP pipeline<br/>[extractor.py]"}}
end

subgraph group_frontend["React UI"]
  node_frontend_app["App shell<br/>React orchestrator<br/>[App.tsx]"]
  node_frontend_extract["API client<br/>network adapter<br/>[extract.ts]"]
  node_frontend_layout["Layout<br/>[layout.ts]"]
  node_frontend_search["Search<br/>ranking helper<br/>[search.ts]"]
  node_frontend_graph["Graph view<br/>xyflow canvas<br/>[GraphView.tsx]"]
  node_frontend_node["Entity node<br/>node renderer<br/>[EntityNode.tsx]"]
  node_frontend_sidebar["Sidebar<br/>panel<br/>[Sidebar.tsx]"]
  node_frontend_text["Text panel<br/>source viewer<br/>[TextPanel.tsx]"]
  node_frontend_main["Main entry<br/>Vite bootstrap<br/>[main.tsx]"]
  node_frontend_indexcss["Styles<br/>CSS<br/>[index.css]"]
  node_build_vite["Vite config<br/>build config<br/>[vite.config.ts]"]
end

subgraph group_docs["References"]
  node_samples_finance["Finance sample<br/>example PDF<br/>[finance.pdf]"]
  node_samples_rohini["Rohini sample<br/>example PDF<br/>[rohini.pdf]"]
  node_docs_walkthrough["Guide<br/>documentation<br/>[DOKUMENTACIO.md]"]
end

node_backend_app -->|"reads pages"| node_backend_pdf_io
node_backend_app -->|"extracts graph"| node_backend_extractor
node_backend_pdf_io -->|"page text"| node_backend_extractor
node_backend_extractor -->|"JSON payload"| node_backend_app
node_frontend_app -->|"loads PDF"| node_frontend_extract
node_frontend_extract -->|"api call"| node_backend_app
node_frontend_app -->|"renders graph"| node_frontend_graph
node_frontend_app -->|"controls"| node_frontend_sidebar
node_frontend_app -->|"selection context"| node_frontend_text
node_frontend_graph -->|"node UI"| node_frontend_node
node_frontend_graph -->|"positions"| node_frontend_layout
node_frontend_sidebar -->|"search input"| node_frontend_search
node_frontend_app -->|"focus state"| node_frontend_search
node_frontend_graph -->|"focus source"| node_frontend_text
node_build_vite -->|"proxy /api"| node_frontend_extract
node_frontend_main -->|"mounts"| node_frontend_app
node_frontend_main -->|"loads styles"| node_frontend_indexcss
node_docs_walkthrough -.->|"documents"| node_backend_app
node_docs_walkthrough -.->|"documents"| node_frontend_app
node_samples_finance -.->|"example input"| node_backend_app
node_samples_rohini -.->|"example input"| node_backend_app

click node_backend_app "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/backend/app.py"
click node_backend_pdf_io "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/backend/pdf_io.py"
click node_backend_extractor "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/backend/extractor.py"
click node_frontend_app "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/App.tsx"
click node_frontend_extract "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/lib/extract.ts"
click node_frontend_layout "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/lib/layout.ts"
click node_frontend_search "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/lib/search.ts"
click node_frontend_graph "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/GraphView.tsx"
click node_frontend_node "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/EntityNode.tsx"
click node_frontend_sidebar "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/Sidebar.tsx"
click node_frontend_text "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/TextPanel.tsx"
click node_frontend_main "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/main.tsx"
click node_frontend_indexcss "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/index.css"
click node_build_vite "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/vite.config.ts"
click node_samples_finance "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/samples/finance.pdf"
click node_samples_rohini "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/samples/rohini.pdf"
click node_docs_walkthrough "https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/docs/DOKUMENTACIO.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_app,node_backend_pdf_io,node_backend_extractor toneBlue
class node_frontend_app,node_frontend_extract,node_frontend_layout,node_frontend_search,node_frontend_graph,node_frontend_node,node_frontend_sidebar,node_frontend_text,node_frontend_main,node_frontend_indexcss,node_build_vite toneAmber
class node_samples_finance,node_samples_rohini,node_docs_walkthrough toneMint
```

## Components

### Python API

FastAPI PDF extraction service

- [API app](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/backend/app.py): FastAPI entrypoint · Starts the Python service and exposes the extraction API. · `backend/app.py`
- [PDF I/O](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/backend/pdf_io.py): pdfplumber adapter · Reads page text and classifies pages as tabular or prose. · `backend/pdf_io.py`
- [Extractor](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/backend/extractor.py): NLP pipeline · Builds graph nodes, edges, and source references from document text. · `backend/extractor.py`

### React UI

Vite frontend for graph viewing and editing

- [App shell](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/App.tsx): React orchestrator · Coordinates upload, fetch, selection, search, and edit state. · `src/App.tsx`
- [API client](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/lib/extract.ts): network adapter · Calls the backend and converts responses into frontend state. · `src/lib/extract.ts`
- [Layout](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/lib/layout.ts): dagre layout · Computes node placement before rendering the graph. · `src/lib/layout.ts`
- [Search](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/lib/search.ts): ranking helper · Ranks nodes for search and drives focus behavior. · `src/lib/search.ts`
- [Graph view](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/GraphView.tsx): xyflow canvas · Renders the editable node-link graph and handles canvas interactions. · `src/components/GraphView.tsx`
- [Entity node](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/EntityNode.tsx): node renderer · Renders individual graph nodes in the canvas. · `src/components/EntityNode.tsx`
- [Sidebar](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/Sidebar.tsx): panel · Handles upload, backend status, and search controls. · `src/components/Sidebar.tsx`
- [Text panel](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/components/TextPanel.tsx): source viewer · Shows matching source text for the selected graph item. · `src/components/TextPanel.tsx`
- [Main entry](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/main.tsx): Vite bootstrap · Mounts the React application into the page. · `src/main.tsx`
- [Styles](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/src/index.css): CSS · Global styling for the frontend. · `src/index.css`
- [Vite config](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/vite.config.ts): build config · Configures development and build-time behavior, including API proxying. · `vite.config.ts`

### References

Sample PDFs and documentation

- [Finance sample](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/samples/finance.pdf): example PDF · Reference input used to demonstrate extraction behavior. · `samples/finance.pdf`
- [Rohini sample](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/samples/rohini.pdf): example PDF · Reference input used to demonstrate extraction behavior. · `samples/rohini.pdf`
- [Guide](https://github.com/kevinyecs/pdf-knowledge-graph/blob/main/docs/DOKUMENTACIO.md): documentation · Hungarian walkthrough of the system and usage. · `docs/DOKUMENTACIO.md`

## Connections

- 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.
