How fabian-beck/survis works
Overall Project Type and Purpose
• SurVis is a literature browser aimed at presenting and analyzing scientific literature collections. It is primarily a frontend web application (with its main entry via src/index.html) that loads bibliographic data from BibTeX files (in the bib directory) along with supplemental configuration and media files.
• There is also an alternative Electron-based implementation (in the electron directory) that serves as a desktop version. An update mechanism is provided via the Python script (update_data.py) that automatically processes the BibTeX file and generates supplemental data files.
Main Components
a. User Interface Layer:
• The primary HTML/CSS/JavaScript based frontend under the src/ directory. This includes:
• src/index.html as the main entry point.
• src/js directory with various JavaScript files (e.g., survis.js for core functionality, additional files for clustering, timeline, selectors, utilities, etc.).
• src/styles for CSS files that style the application.
• Additionally, static pages like src/about.html and specialized pages provide the app’s content.
b. Data Management:
• The bibliography data from the BibTeX file located at bib/references.bib.
• Supplemental data stored under src/data/ (lists of tags, categories, stopwords, image and PDF directories) which the UI uses to organize and filter literature.
c. Update/Preprocessing Component:
• The update_data.py script which is executed (using Python 3) to read the BibTeX file and output processed data files in src/data/generated/.
• This component represents how the raw bibliographic data is formatted and prepared for use by the frontend.
d. Alternative Desktop Mode (Electron):
• The electron/ directory contains files for a desktop application version (index-electron.html, index.js, package files, etc.) that likely wraps the web interface into an Electron shell.
• This component shows that the system is not strictly just a browser-based application, but also has a packaged desktop version.
e. External Interactions:
• Mention any external resources (such as the reference literature databases mentioned in the README) if relevant, though the primary architecture is self-contained.
• Integration with other tools for modifying and persisting data (e.g., local storage mechanisms when edit mode is enabled).
Relationships and Data Flow
• How the raw bibliography data (bib/references.bib) flows into the preprocessing/update component (update_data.py), which then writes or updates the generated data in src/data/generated/.
• That the frontend (running out of src/index.html along with JavaScript files) loads data from the src/data folder. This data then feeds into various UI components (e.g., references view, timeline, and clustering visualization).
• In the Electron version, indicate that the desktop application essentially wraps the same front-end logic while possibly providing desktop-specific integrations or configuration.
Architectural Patterns and Design Principles
• Frontend-Backend (or, more precisely, client-preprocessing) separation: Although all files are served as static files in a browser, there is a clear separation between:
– the presentation layer (HTML/CSS/JS in src)
– the data input and configuration (bib and src/data)
– the data preprocessing/updating script (update_data.py).
• The usage of modular JavaScript libraries (shown in src/js/lib) also suggests a design that emphasizes separation of concerns in the codebase.
• Automated update cycle where the Python script watches for changes to the bibliography file and updates generated configurations accordingly.
Final Recommendations
• Key files and directories (as seen in the file tree) that contribute to the application’s operation are clearly represented.