# willsephton/masters-dissertation-prototype architecture

> Architecture diagram of the GitHub repository willsephton/masters-dissertation-prototype, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/willsephton/masters-dissertation-prototype
- Repository: https://github.com/willsephton/masters-dissertation-prototype

## Overview

The product is a web prototype for exploring PDF and PowerPoint documents in traditional and structured views. Its main workflow converts presentations for PDF viewing, extracts document structure and images, adds OCR and GPT-4o descriptions and summaries, then presents generated JSON alongside the original document with navigation and page synchronization. The README describes these capabilities; the graph uses the sampled server, pipeline, parser, and viewer sources, so some frontend wiring and generated-output details remain uncertain.

Main entry points: [`public/scripts/python-pipeline-scripts/pipeline_recursive.py`](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/pipeline_recursive.py) (Document pipeline), [`public/scripts/enhancedviewer.js`](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/enhancedviewer.js) (Structured viewer), [`public/scripts/python-pipeline-scripts/gpt4o_functions.py`](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/gpt4o_functions.py) (AI descriptions), [`public/scripts/filelist.js`](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/filelist.js) (PDF selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_filelist["PDF selection<br/>[filelist.js]"]
  node_filehandler["File selection handler<br/>[fileListHandler.js]"]
  node_pdfviewer["Traditional viewer<br/>[pdfviewer.js]"]
  node_enhanced["Structured viewer<br/>[enhancedviewer.js]"]
end

subgraph group_server["Server orchestration"]
  node_server["Express server<br/>[app.mjs]"]
  node_converter["PPTX conversion"]
  node_runner["Pipeline launcher<br/>[mlPipeline.js]"]
end

subgraph group_extract["Document extraction"]
  node_pipeline["Document pipeline"]
  node_pdfparser["PDF parser<br/>[pdf_parser.py]"]
  node_pptxparser["PowerPoint parser<br/>[pptx_parser.py]"]
  node_ocr["EasyOCR"]
end

subgraph group_enrichment["AI enrichment"]
  node_gpt["AI descriptions<br/>[gpt4o_functions.py]"]
  node_outputs["Generated JSON and images"]
  node_summaries["Summary index<br/>[gpt4o_functions.py]"]
end

node_reader(("Document reader"))
node_openai["OpenAI GPT-4o"]
node_documents["PDF and PPTX files"]
node_pdfcopies["Converted PDFs"]

node_reader -->|"selects documents"| node_filelist
node_filelist -->|"requests PDF list"| node_server
node_server -->|"returns PDF list"| node_filelist
node_filelist -->|"loads PDF"| node_pdfviewer
node_filelist -->|"loads JSON view"| node_enhanced
node_reader -->|"selects file"| node_filehandler
node_filehandler -->|"loads PDF"| node_pdfviewer
node_filehandler -->|"loads JSON view"| node_enhanced
node_reader -->|"navigates pages"| node_enhanced
node_enhanced -->|"syncs page"| node_pdfviewer
node_server -->|"calls conversion"| node_converter
node_converter -->|"reads presentations"| node_documents
node_converter -->|"writes PDFs"| node_pdfcopies
node_server -->|"starts pipeline"| node_runner
node_runner -->|"spawns script"| node_pipeline
node_pipeline -->|"reads documents"| node_documents
node_pipeline -->|"parses PDFs"| node_pdfparser
node_pipeline -->|"parses presentations"| node_pptxparser
node_pdfparser -->|"recognizes image text"| node_ocr
node_pptxparser -->|"recognizes image text"| node_ocr
node_pipeline -->|"adds descriptions"| node_gpt
node_gpt -->|"requests descriptions"| node_openai
node_gpt -->|"requests summaries"| node_openai
node_pipeline -->|"writes extracted data"| node_outputs
node_gpt -->|"reads document JSON"| node_outputs
node_gpt -->|"writes summaries"| node_summaries
node_enhanced -->|"fetches JSON and images"| node_outputs
node_enhanced -->|"fetches summaries"| node_summaries

click node_server "https://github.com/willsephton/masters-dissertation-prototype/blob/main/app.mjs"
click node_filelist "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/filelist.js"
click node_filehandler "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/fileListHandler.js"
click node_pdfviewer "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/pdfviewer.js"
click node_enhanced "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/enhancedviewer.js"
click node_converter "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/convertPptxToPdf.js"
click node_runner "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/mlPipeline.js"
click node_pipeline "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/pipeline_recursive.py"
click node_pdfparser "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/pdf_parser.py"
click node_pptxparser "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/pptx_parser.py"
click node_gpt "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/gpt4o_functions.py"
click node_summaries "https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/gpt4o_functions.py"
click node_documents "https://github.com/willsephton/masters-dissertation-prototype/tree/main/public/docs"
click node_pdfcopies "https://github.com/willsephton/masters-dissertation-prototype/tree/main/public/pptx-pdfs"

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_filelist,node_filehandler,node_pdfviewer,node_enhanced toneBlue
class node_server,node_converter,node_runner toneAmber
class node_pipeline,node_pdfparser,node_pptxparser,node_ocr toneMint
class node_gpt,node_outputs,node_summaries toneRose
class node_reader,node_openai toneIndigo
class node_documents,node_pdfcopies toneTeal
```

## Components

### Web experience

- [PDF selection](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/filelist.js): `public/scripts/filelist.js`
- [File selection handler](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/fileListHandler.js): `public/scripts/fileListHandler.js`
- [Traditional viewer](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/pdfviewer.js): `public/scripts/pdfviewer.js`
- [Structured viewer](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/enhancedviewer.js): `public/scripts/enhancedviewer.js`

### Server orchestration

- [Express server](https://github.com/willsephton/masters-dissertation-prototype/blob/main/app.mjs): `app.mjs`
- [PPTX conversion](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/convertPptxToPdf.js): `public/scripts/convertPptxToPdf.js`
- [Pipeline launcher](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/mlPipeline.js): `public/scripts/mlPipeline.js`

### Document extraction

- [Document pipeline](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/pipeline_recursive.py): `public/scripts/python-pipeline-scripts/pipeline_recursive.py`
- [PDF parser](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/pdf_parser.py): `public/scripts/python-pipeline-scripts/pdf_parser.py`
- [PowerPoint parser](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/pptx_parser.py): `public/scripts/python-pipeline-scripts/pptx_parser.py`
- **EasyOCR**

### AI enrichment

- [AI descriptions](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/gpt4o_functions.py): `public/scripts/python-pipeline-scripts/gpt4o_functions.py`
- **Generated JSON and images**
- [Summary index](https://github.com/willsephton/masters-dissertation-prototype/blob/main/public/scripts/python-pipeline-scripts/gpt4o_functions.py): `public/scripts/python-pipeline-scripts/gpt4o_functions.py`

### Other components

- **Document reader**
- **OpenAI GPT-4o**
- [PDF and PPTX files](https://github.com/willsephton/masters-dissertation-prototype/tree/main/public/docs): `public/docs`
- [Converted PDFs](https://github.com/willsephton/masters-dissertation-prototype/tree/main/public/pptx-pdfs): `public/pptx-pdfs`

## Connections

- Document reader → PDF selection: selects documents
- PDF selection → Express server: requests PDF list
- Express server → PDF selection: returns PDF list
- PDF selection → Traditional viewer: loads PDF
- PDF selection → Structured viewer: loads JSON view
- Document reader → File selection handler: selects file
- File selection handler → Traditional viewer: loads PDF
- File selection handler → Structured viewer: loads JSON view
- Document reader → Structured viewer: navigates pages
- Structured viewer → Traditional viewer: syncs page
- Express server → PPTX conversion: calls conversion
- PPTX conversion → PDF and PPTX files: reads presentations
- PPTX conversion → Converted PDFs: writes PDFs
- Express server → Pipeline launcher: starts pipeline
- Pipeline launcher → Document pipeline: spawns script
- Document pipeline → PDF and PPTX files: reads documents
- Document pipeline → PDF parser: parses PDFs
- Document pipeline → PowerPoint parser: parses presentations
- PDF parser → EasyOCR: recognizes image text
- PowerPoint parser → EasyOCR: recognizes image text
- Document pipeline → AI descriptions: adds descriptions
- AI descriptions → OpenAI GPT-4o: requests descriptions
- AI descriptions → OpenAI GPT-4o: requests summaries
- Document pipeline → Generated JSON and images: writes extracted data
- AI descriptions → Generated JSON and images: reads document JSON
- AI descriptions → Summary index: writes summaries
- Structured viewer → Generated JSON and images: fetches JSON and images
- Structured viewer → Summary index: fetches summaries
