# fabian-beck/survis architecture

> Architecture diagram of the GitHub repository fabian-beck/survis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fabian-beck/survis
- Repository: https://github.com/fabian-beck/survis

## Overview

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

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data Pipeline"
        BD["Bibliography Data (BibTeX)"]:::datasource
        DP["Data Preprocessing (Update Engine)"]:::processing
        SD["Supplementary Data & Config"]:::data
    end

    subgraph "Presentation Layer"
        UI["Frontend UI (Presentation Layer)"]:::frontend
    end

    E["Electron Desktop Application (Desktop)"]:::electron

    BD -->|"parses"| DP
    DP -->|"generates"| SD
    SD -->|"supplies"| UI
    E -->|"wraps"| UI

    click BD "https://github.com/fabian-beck/survis/blob/master/bib/references.bib"
    click DP "https://github.com/fabian-beck/survis/blob/master/update_data.py"
    click SD "https://github.com/fabian-beck/survis/tree/master/src/data/"
    click UI "https://github.com/fabian-beck/survis/tree/master/src/"
    click E "https://github.com/fabian-beck/survis/tree/master/electron/"

    classDef datasource fill:#F1948A,stroke:#333,stroke-width:2px;
    classDef processing fill:#A3E4D7,stroke:#333,stroke-width:2px;
    classDef data fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef frontend fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef electron fill:#F5B7B1,stroke:#333,stroke-width:2px;
```
