System Design Document for Citation Graph

Team Members:

• Aaron Van De Brook
• Corrina Del Greco
• Luis Mora
• Samantha Shultz
• Sultan Alteneiji

Version/Author	Date
1.0	02.18.2021
2.0	03.18.2021
3.0	04.13.2021

Table of Contents

1. Introduction

• 1.1 Purpose and Scope
• 1.2 Project Executive Summary
  • 1.2.1 System Overview
  • 1.2.2 Design Constraints
  • 1.2.3 Future Contingencies
• 1.3 Document Organization
• 1.4 Project References
• 1.5 Glossary

2. System Architecture

• 2.1 System Software Architecture
• 2.2 Internal Communications Architecture

3. Human-Machine Interface

• 3.1 Inputs
• 3.2 Outputs

4. Detailed Design

• 4.1 Software Detailed Design
• 4.2 Internal Communications Detailed Design

5. External Interfaces

• 5.1 Interface Architecture
• 5.2 Interface Detailed Design

6. System Integrity Controls

System Design Document

Overview The System Design Document describes the system requirements, operating environment, system and subsystem architecture, files and database design, input formats, output layouts, human-machine interfaces, detailed design, processing logic, and external interfaces.

1. Introduction

1.1 Purpose and Scope

The purpose of the System Design Document is to describe the system requirements, operating environment, system and sub-system architecture, files and database design, input formats, output layouts, human-machine interfaces, detailed design, processing logic, and external interfaces for the Citation Graph project.

1.2 Project Executive Summary

This section provides an overview of the Citation Graph project and shows the framework with which the system design was conceived.

1.2.1 System Overview

The system is a web-based tool with which a user can input research papers, view graphs of the citations, and add necessary info. The system will accept research papers that contain references in the LaTeX/BibTeX format in order to output a visual dependency graph that shows the dependencies between the paper and its references. An important contribution that this project will give to already developed citation graphs is the allowance for the user to modify and add information about the papers. The diagram below shows interfaces to external systems and a high-level view of the requirements the system will fulfill.

The purpose of the project is to create a software tool which can display the dependencies between a paper and its references. The user will be able to view the dependencies between the papers and will be able to add to and modify information about the papers. Every paper added will contribute to the database used for information look-ups.

The project relies on various different software and frameworks. Doxygen, HTML, CSS, C, LaTeX, and BibTeX are all being used to create the tool. The project will be be undertaken within three sprints. The first sprint will mostly consist of research to be able to decide which method will be used to approach the creation of the tool, and the following sprints will produce the final usable product.

1.2.2 Design Constraints

The largest constraint in the system design is that Doxygen, the tool used to generate the graph documentation, cannot take LaTeX or BibTeX as an input. A trade-off analysis was conducted to determine if the developement team would extend Doxygen's functionality to interpret LaTeX files or create a tool that translates LaTeX files to a language that Doxygen can interpret, like C. The latter option was chosen.

1.2.3 Future Contingencies

Doxygen includes default layouts to display the graphical information. Editing the layouts is not possible; however, to display edited information, a custom layout will be better. The team has yet to determine whether or not they can create a tool to handle the GUI functionality extension.

1.3 Document Organization

This System Design Document is organized into six sections, including this introduction section. Following this, the document will go over the system architecture, the human-machine interface, the software and internal communications design, external interfaces, and the system integrity controls.

1.4 Project References

• SRS

1.5 Glossary

• BibTeX - A bibliography system/format meant to be used as an extension to LaTeX, files have an extension of .bib
• Doxygen - A tool for generating software reference documentation
• LaTeX - A typesetting system/format for writing papers and documentation, files have an extension of .tex

2. System Architecture

This section describes an overview of the software architecture for the Citation Graph system and subsystems.

2.1 System Software Architecture

Note: As of version 1.0 of this document, the primary concern is the back-end design. It is assumed that Doxygen, given the right inputs, will generate the front-end HTML. This is a early iteration of the Citation Graph Project.

The system accepts the user's research paper(s). The system requires it to be in LaTeX with BibTeX citations.

The system uses the BibTeX citations to create a file in a language that Doxygen can handle, which for the purpose of the project is C. BibTeX resembles a dictionary (i.e. author="Corrina") of attributes (information about the paper). Doxygen cannot handle BibTeX, so the system will convert it to C. The C code will not be functional, it's simply a way to speak to Doxgyen in a language it will understand.

Doxygen generates the graph using the C framework and it provides HTML for our GUI. Graph nodes are paper names and graph connections are the references to other papers. A purely Doxygen-generated front end will be the initial design, though later, the developers may make their own front-end.

The user can modify and add fields and the program will rewrite the files that are used by Doxygen to regenerate the graph. Initially, this will be done by the user editing the files in a text editor and later the developers could create their own GUI with fillable forms. For example, a new page opens for Paper A with a form to change existing fields such as the author or allow to add new fields such as a summary.

2.2 Internal Communications Architecture

The entire system is separated into two "ends". A "front-end" responsible for managing input to and output of the system and a "back-end" responsible for processing and managing data. Communication within the respective "ends" of the system will be done simply through function calls. However, communication between "ends" is done through REST API calls to endpoints in the back-end which will be expedited by Flask. Endpoints are set up in the back-end to handle and serve requests for information such as graph trees, paper information, etc. as applicable and/or as necessary.

3. Human-Machine Interface

This section provides the detailed design of the system inputs and outputs relative to the user.

3.1 Inputs

The input media used by the user to provide information to the system will be text files. The user will provide their research paper(s) and the system requires this input to be in the LaTeX/BibTeX format This format is commonly used in the research community. This means that if a research paper is a PDF or Word Document, it will not be and accepted input.

There are several inputs the system may expect within this LaTeX/BibTeX limitation. The first, as one might expect, is the complete research paper. The second is a LaTeX file that pairs 1:1 with that research paper, but is shorter in length and contains only information directly relevant to the Citation Graph Project. The term "reduced" paper has been coined for this input. It will have a naming convention of LastNameYear (i.e. Liu2008.tex.) and the expected attributes for the reduced LaTeX file include:

• Title/author/affiliation
• Abstract
• Index terms
• Most import contributions
• Citation graph

Another input is a BibTeX file called all.bib. The relationship between the all.bib file and the papers is a one-to-many relationship. The all.bib file contains a brief set of information for the identification of the related research papers. An example except from an all.bib is shown below.

@manual{A41102,
    title   = "A Users' Guide for the {A}41102",
    year    = "Austeck Microsystems, 1988"}

@article{Abidi1995,
    author  = {A.~A.~Abidi},
    title   = "Direct-Conversion Radio Transceivers for Digital Communications",
    journal = "IEEE Journal of Solid-State Circuits",
    year    = "1995",
    volume  = "30",
    number  = "",
    month   = "December",
    pages   = "1399--1410"}

@book{Abramson1963,
    author  = {N. Abramson},
    title   = "{I}nformation Theory and Coding",
    publisher= "McGraw-Hill Book Co.",
    address = "New York, NY",
    year    = "1963"}

3.2 Outputs

Because of the way the system is designed, there will be many "outputs" throughout the system as modules pass and process data between each other. These will be described in more detail in section 4.1. In terms of output that the user will be able to see and interact with, there will be a graphical representation of what each paper depends on and what references one another. Each node of the graph will display information about that specific paper such as titles, authors, publication date, etc. The nodes will also be editable in order for the user to add more information or correct inaccurate information.

4. Detailed Design

This section contains detailed information about the software design of the system.

4.1 Software Detailed Design

The system is split up into modules, each with its own specific atomic purpose, similarly to the Unix philosophy of "each program has 1 specific task". Each module will be described in detail in their own subsection below.

4.1.1 The LaTeX and BibTeX Parsers

These are included in the same section because they are treated as one module by the other modules in the system. This means that they will both receive the same input and contribute to the same output which will be used by subsequent modules.

The LaTeX parser is responsible for analyzing the paper input by the user (in LaTeX form) and extracting sections which the development team, customer, and product owner have deemed to be important. Examples include the paper title, author names, abstract, and citations/references.

The BibTeX parser operates similarly with the main difference being that it will only process the paper citations. This is becausethey will be provided by the user in a different format, the BibTeX form. From these citations similar information will also be extracted and stored as necessary with the paper identification, title, and authors being among the most important pieces of information.

The last step of this module is to convert all this data into a C-like function representation, which will be assembled and run through Doxygen to do the graph and documentation generation which will be used as output to the user.

4.1.2 The Doxygen Module

The C-like functions that were generated by the parsers are assembled so that they can be run through the Doxygen program to automatically generate the graph and documentation. This will be displayed to the user on the front-end. There are configuration files that Doxygen requires in order to run correctly on a set of input files, so these will be automatically generated and maintained as necessary to conform to the needs of the system/project.

4.1.3 The Database Module

To improve the responsiveness of the system, a database module is necessary to store preprocessed information and serve it on demand to the user and/or to the front-end system components as necessary.

This module will start as a simple system that reads and writes ASCII data to files as needed throughout normal use, but will become more sophisticated as the system develops.

4.1.4 The Server Module

This module is primarily a web application and includes a server to broker connections and requests for data from the user and front-end components. Most of this will be managed by Flask, a web application framework, so all that needs to be done is to set up endpoints and their responses.

The server will also be responsible for the initialization of other modules upon startup, such as the database and possibly Doxygen depending on how the configuration files are set up.

4.2 Internal Communications Detailed Design

As stated previously, the communication between modules will be primarily through public function calls along with input/output data from the modules. The communication within each end of the system will be very straight forward, so all that will need to be known of what parameters a function will need and what data it returns.

Communication between the front and back end of the system will be slightly more complicated. Luckily, some of this is abstracted away for us by using the Flask micro-service. REST endpoints will be the primary means of communication between each end of the system. The server will "broker" or manage all of the incoming connections and requests and hand them off to other modules and/or respond as necessary.

5. External Interfaces

This section will examine the external systems that will interact with the Citation Graph system.

5.1 Interface Architecture

At the current phase of the design, the only systems that will be able to interact with the system are web browsers and other programs that can make individual API calls (like Curl). To make it easy to communicate with the browser, HTML and CSS will be used to style the front-end and provide a GUI for the user. JavaScript will be used to make client-side requests to the server operating in the "back-end".

5.2 Interface Detailed Design

The API endpoints have not yet been fully detailed. Not many are planned for use as of Sprint 1. As the system becomes more fully developed, the API documentation will be added here as well as in the README and/or other wikis.