Team

Code contributor docs

This document is for someone developing the LXCat web application and its packages.

Where is the code?

Code is hosted on https://github.com/LXCat-project/lxcat. Code to fill the database can be found in /packages/database. Code that runs the website can be found in /app. Code that describes the shape of LXCat documents can be found in /packages/schema. Code that can convert LXCat documents to txt format can be found in /packages/converter.

How to perform local deployment with test data?

See /packages/database how to seed the database with test data.

How to make a pull request

See the GitHub documentation on pull requests how to create a pull request in repository.

Documentation

The documentation is formatted in GitHub flavored Markdown files in the /docs directory.

The documentation is also hosted on the website at https://<domain of lxcat website>/docs.

To have working links between Markdown files on the website use URLs without the .md extension.

The following features are available in Markdown

Code highlighting

Code block will be highlighted. For example

```ts
function add(a: string, b: string): string {
  return a + b;
}
```

is highlighted as

function add(a: string, b: string): string {
  return a + b;
}

Local images

For example show the ./screenshot.png image inside Markdown file use ![](screenshot.png). The path of the image should be relative to the Markdown file..

Diagrams

You can add code blocks using mermaidjs format to render diagrams.

For example

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

is rendered as

Math

LaTeX equations can be added by wrapping the equation with $$.

For example

$$ L = \frac{1}{2} \rho v^2 S C_L $$

is rendered as

L=12ρv2SCLL = \frac{1}{2} \rho v^2 S C_L

Technology wishes

Wishes for the pieces of software to be used.

Stack should be stable and usable by maintainers of lxcat.

The current lxcat is written in PHP and uses Mysql as database with phpmyadmin as admin interface. In the new lxcat, the admin interface should be part of the web application and offer some one to upload or edit a cross section set using a web form. This new interface should be behind a login.

The prototype by Daan Boer is written in Typescript and uses Arangodb as database. For the new lxcat we want to keep using TypeScript and ArangoDB.

The current lxcat uses a time machine to show previous versions of data. The current lxcat can show the whole lxcat website as it was at a date in the past. This time machine is mainly there to have a reference in a paper to a certain version of data. The new lxcat must also allow for showing previous versions of data for proper referencing aswell. Instead of a time machine implementation, we want to have multiple versions for each cross section or each cross. Similar to Zenodo or Uniprot

Full stack web framework

Whishes:

  • renders most HTML on server
  • reuse layout
  • styled using ui framework like material or antd
  • external authentication
  • api with openapi
  • markdown
  • db agnostic

Schema / validation

  • Autocomplete for developer IDE -> Typescript
  • Validate at boundaries like incoming request
  • Validate during inserting/updating into database with JSON schema
  • Support complex schemas like cross section document
  • Cross language: Should be able to generate or use JSON schemas
  • Schema should be rich
    • title and description
    • min/max/length/etc. validation rules

Possible options see https://learning-notes.mistermicheels.com/javascript/typescript/runtime-type-checking

Technology choices

  • Database = ArangoDB
  • Programming language = TypeScript
  • Web framework = NextJS
  • UI framework = React
  • UI style framework = Mantine
  • API framework = API pages in NextJS
  • App authentication = OpenID identity providers + next-auth
  • API authentication = (OpenID identity providers + next-auth) or JWT based API token
  • Authorization = roles assigned to users
  • OpenID identity provider = Orcid or Keycloak
  • Schema = Zod, used for validation, typescript type, JSON schema for API consumers and database collection
  • Database seeding and migration = Handrolled directory importer
  • Configuration = dotenv
  • Production deployment = docker-compose
  • Development deployment = Database in Docker container and app on bare-metal

Debugging

In Visual Studio Code you can debug the server, client or fullstack by using the /.vscode/launcher.json file. See NextJS debugging docs and VS Code docs for more info.

Database diagram

The following diagram shows all document and edge collections.

The columns mentioned are for illustration. Each document collection has a JSON schema (defined in /packages/database/src/**/schema.ts) which defines the shape of each document inserted/updated.

The diagram can be edited on https://mermaid.live/ by copying the code block text.

Unit Tests

Tests can be written as src/**/*.{test,spec}.ts files with vitest framework and run with

pnpm test

To run tests with code coverage use

pnpm test -- run --coverage
xdg-open coverage/index.html

To debug tests in VS code

  1. Place a breakpoint or debugger statement in code
  2. In Debug sidebar select Debug Current Test File
  3. Focus on test file
  4. Press F5

Licensing

This project uses GNU Affero General Public License v3.0 or later for the web application and any package not published to npmjs.com. The Apache 2.0 license is used for packages published to npmjs.com.

This project uses the REUSE software recommendations for licensing and copyright.

To test compliance use

python3 -m venv .venv
. .venv/bin/activate
pip install reuse
reuse lint

To add headers to files run pnpm annotate or if that fails add header manually.

For binary files or text files without comment support a <original file name>.license file can be made, alternativly add file in /.reuse/dep5 file.

Publishing software

If there are changes to the code you want to cite you will need to create a new Digital Object Identifier (DOI).

To create a new DOI:

  1. Bump package versions in package.json files, rerun pnpm install, commit & push to main branch.
  2. Create a new GitHub release.
  3. On Zenodo page for LXCat, a new version needs to be created with the tarball of the new release.