Sequence Matching

This is the repository of the sequence matching tool

Getting Started

Follow the instruction guide at seqMGuide

or SDIGuide

Note: Make sure that you have one of the BiopharmaFinder versions below

Version	Release Date	Change Log	Validated	Reference
5.0	2023	Workflow-driven experiment creation, method processing, and result review	✅	Release Notes
5.3	2024	Enhanced peptide mapping, oligonucleotide analysis, intact protein analysis, top-down analysis	❌	Product Page

Architecture

The application consists of two parts:

• Backend – a FastAPI server (Python) that runs the sequence matching algorithm and streams results over a WebSocket connection. It listens on port 8000 by default.
• Frontend – a React single-page application that is deployed to GitHub Pages. It communicates with the backend over WebSocket (wss://) and HTTP (https://).

---

Local Installation & Running

Follow these steps to install and run both the backend and the frontend on your machine for local development.

Prerequisites

Tool	Minimum Version	Notes
Python	3.9	Required for the backend
Node.js	16	Required for the frontend
npm	8	Bundled with Node.js
Git	any

Backend (Python / FastAPI)

1. Create a virtual environment

macOS / Linux (bash/zsh):

python -m venv wiz-app-env
source wiz-app-env/bin/activate

Windows (PowerShell):

python -m venv wiz-app-env
wiz-app-env\Scripts\Activate.ps1

2. Install the package and its dependencies

pip install -e .

3. Start the backend server

uvicorn server.app:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000.
Interactive API docs (Swagger UI) are served at http://localhost:8000/docs.

Frontend (React)

1. Install JavaScript dependencies

npm install

2. Configure URLs in one place

Copy .env.example to .env and update the URL values:

# macOS/Linux
cp .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env

Set these for local development:

REACT_APP_BACKEND_URL=http://localhost:8000
REACT_APP_FRONTEND_URL=http://localhost:3000
FRONT_END_URL=http://localhost:3000

The frontend reads URL exports from src/config/urls.ts, and the backend reads FRONT_END_URL from .env.

3. Start the React development server

npm start

The frontend will be available at http://localhost:3000 and will automatically reload when you edit source files.

---

Docker

Docker images are provided for both services. Build them from the repository root.

Backend

Build the image

docker build -f Dockerfile.backend -t sequence-matching-backend .

Run the container

docker run -p 8000:8000 sequence-matching-backend

The -p 8000:8000 flag maps port 8000 inside the container to port 8000 on your host machine, so the API is reachable at http://localhost:8000.

To run in detached (background) mode:

docker run -d -p 8000:8000 --name seq-backend sequence-matching-backend

Stop it later with:

docker stop seq-backend

Frontend

Build the image

docker build -f Dockerfile.frontend -t sequence-matching-frontend .

Run the container

docker run -p 3000:3000 sequence-matching-frontend

The frontend will be available at http://localhost:3000.

Running Both Services Together

You can start both containers at the same time using separate terminal windows, or chain the commands:

# Terminal 1 – backend
docker run -p 8000:8000 --name seq-backend sequence-matching-backend

# Terminal 2 – frontend
docker run -p 3000:3000 --name seq-frontend sequence-matching-frontend

---

Deploying the Backend so the GitHub Pages Frontend Can Use It

The frontend is hosted on GitHub Pages (HTTPS). Because browsers block mixed content, the backend must also be served over HTTPS for the GitHub Pages frontend to connect to it.

Option 1 – Deploy to a Cloud Platform (recommended for production)

The repository is pre-configured for Railway via railway.toml and Dockerfile.backend. Push the repository to Railway and it will automatically build and deploy the backend, providing a public https:// URL.

1. Create a Railway project and link this repository.
2. Railway will detect railway.toml and build the backend image.
3. Copy the deployment URL (e.g. https://your-app.up.railway.app).
4. Update .env values:
   • REACT_APP_BACKEND_URL=https://your-app.up.railway.app
   • REACT_APP_FRONTEND_URL=https://your-frontend-domain
   • FRONT_END_URL=https://your-frontend-domain
5. Commit and push; then redeploy frontend/backend so both sides pick up the new environment values.

Other platforms that work with Dockerfile.backend include Render, Fly.io, and any VPS running Docker.

Option 2 – Expose a Local Docker Container with ngrok (for temporary / testing use)

If you want to test the GitHub Pages frontend against a backend running on your local machine, you can use ngrok to create a secure public HTTPS tunnel.

Prerequisites

Install ngrok: https://ngrok.com/download

Steps

1. Start the backend container (see the Docker section above):

   docker run -p 8000:8000 sequence-matching-backend

2. In a second terminal, start an ngrok tunnel to port 8000:

   ngrok http 8000

3. ngrok will print a public URL such as https://<your-ngrok-subdomain>.ngrok-free.app. Copy it.

4. Update .env so the browser connects to your tunnel (replace <your-ngrok-subdomain> with the value from step 3):

   • REACT_APP_BACKEND_URL=https://<your-ngrok-subdomain>.ngrok-free.app
   • REACT_APP_FRONTEND_URL=http://localhost:3000 (or your deployed frontend URL)
   • FRONT_END_URL=http://localhost:3000 (or your deployed frontend URL)

5. Rebuild and redeploy the frontend, or run npm start locally and open the app in your browser.

Note: The free ngrok URL changes every time you restart the tunnel. For a stable URL, use a paid ngrok plan or deploy to a cloud platform (Option 1).

Option 3 – Self-host on a VPS or Server

1. SSH into your server and ensure Docker is installed.
2. Clone this repository and build the backend image:

   git clone https://github.com/kesler20/sequence_matching.git
   cd sequence_matching
   docker build -f Dockerfile.backend -t sequence-matching-backend .

3. Run the container, forwarding port 8000 to the host:

   docker run -d -p 8000:8000 --name seq-backend --restart unless-stopped sequence-matching-backend

4. Set up a reverse proxy (e.g. nginx or Caddy) with an SSL certificate (e.g. from Let's Encrypt) so the backend is reachable as https://your-domain.com.
5. Update .env URL values and redeploy.

---

GitHub Pages Deployment

The frontend is automatically deployed to GitHub Pages when changes are pushed to the master branch. The workflow is defined in .github/workflows/ci-cd-gh-pages.yml and performs the following steps:

1. Installs dependencies with pnpm.
2. Runs TypeScript type checking.
3. Builds the production bundle (pnpm run build).
4. Deploys the dist/ folder to GitHub Pages.

The live frontend URL is shown in the repository's Environments section on GitHub.

---

Configuration

Location	Variable / Export	Default value	Description
.env	REACT_APP_BACKEND_URL	https://wiz-app-production.up.railway.app	Single backend base URL used by the frontend
src/config/urls.ts	BACKEND_URL, BACKEND_WS_URL, FRONTEND_URL	derived from .env	Frontend URL exports consumed across the app
.env	FRONT_END_URL	https://wiz-app.up.railway.app	Frontend origin added to backend CORS allow-list

When deploying to a new environment, update .env values in one place.

---

TODOs

• provide the .gist with the credentials