Frontend Development

ASKCOS Web Documentation

Overview

ASKCOS Web is the frontend application for the ASKCOS (Computer-aided Design Tools for Organic Synthesis) platform. It provides a user interface for predicting feasible synthetic routes towards desired compounds and managing synthesis planning tasks.

Project Structure

askcos-vue-nginx/
├── askcos_vue/           # Main Vue.js application
│   ├── src/             # Source code
│   ├── public/          # Static assets
│   ├── cypress/         # End-to-end tests
│   └── dist/            # Production build output
├── Dockerfile           # Docker configuration
├── .gitlab-ci.yml       # CI/CD pipeline configuration
└── Makefile            # Build and deployment scripts

Technology Stack

• Frontend Framework: Vue.js 3
• UI Framework: Vuetify 3
• State Management: Pinia
• Build Tool: Vite
• Testing: Jest, Cypress
• Authentication: Keycloak
• 3D Visualization: Three.js, 3DMol
• Data Visualization: Chart.js, vis-network
• Type Checking: Flow

Getting Started

Prerequisites

• Node.js (Latest LTS version recommended)
• npm or yarn
• Docker (for containerized deployment)

Node.js Version Requirements

The project is built with modern JavaScript features and requires Node.js version 16 or higher. We recommend using Node.js LTS (Long Term Support) version for the best stability and compatibility.

Version Compatibility

• Minimum Version: Node.js 16.x
• Recommended Version: Node.js 18.x LTS or 20.x LTS
• Package Manager: npm 7+ or yarn 1.22+

To check your Node.js version:

node --version

To check your npm version:

npm --version

If you need to manage multiple Node.js versions, we recommend using a version manager like nvm (Node Version Manager):

# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use the recommended Node.js version
nvm install 18
nvm use 18

Installation

1. Clone the repository:

git clone https://gitlab.com/mlpds_mit/askcosv2/askcos-vue-nginx.git
cd askcos-vue-nginx

2. Install dependencies:

cd askcos_vue
npm install

Development

To start the development server:

npm run dev

The application will be available at http://localhost:3000 by default.

Building for Production

To create a production build:

npm run build

The built files will be in the dist directory.

Testing

Unit Tests

npm run test

End-to-End Tests

npm run cy:open

Docker Deployment

The application can be deployed using Docker:

docker build -t askcos-vue .
docker run -p 80:80 askcos-vue

Key Features

1. Synthesis Planning

   • Route prediction for target compounds
   • Interactive reaction network visualization
   • 3D molecular structure viewing

2. User Interface

   • Modern, responsive design
   • Interactive data visualization
   • Real-time updates

3. Authentication & Security

   • Keycloak integration
   • Secure API communication
   • Role-based access control

Development Configuration Guide

Backend Endpoint Configuration

During development, you may need to connect to different backend endpoints (e.g., local development server, staging server, or production server). This guide explains how to configure the backend endpoints in the Vite development server.

Current Configuration

The project uses Vite's proxy configuration to forward API requests to the backend server. By default, the configuration in vite.config.js looks like this:

const fastapiGatewayPtr = {
  target: "http://x.x.x.x/",
  changeOrigin: true,
  ws: true,
  secure: false,
};

// In the server configuration
server: {
  host: "0.0.0.0",
  port: 3000,
  proxy: {
    "/openapi.json": fastapiGatewayPtr,
    "/docs": fastapiGatewayPtr,
    "/api/": fastapiGatewayPtr,
  },
}

Changing the Backend Endpoint

1. Open askcos_vue/vite.config.js
2. Locate the fastapiGatewayPtr configuration
3. Change the target value to your desired backend URL:

const fastapiGatewayPtr = {
  target: "http://your-backend-url/",  // Change this URL
  changeOrigin: true,
  ws: true,
  secure: false,
};

Proxy Configuration Details

The proxy configuration handles several types of requests:

• /openapi.json - OpenAPI/Swagger documentation
• /docs - API documentation interface
• /api/ - All API endpoints

2. Verify the backend connection:
   • Open your browser's developer tools
   • Check the Network tab
   • Look for API requests to ensure they're being proxied correctly

Troubleshooting

1. CORS Issues

   • If you see CORS errors, ensure changeOrigin: true is set in the proxy configuration
   • Check that your backend server allows requests from your development server

2. SSL/HTTPS Issues

   • If connecting to an HTTPS backend, you might need to set secure: false to allow self-signed certificates
   • For production, ensure proper SSL certificates are in place