BGC Viewer

Badges
Build Status
Software Directory
License
Fairness

A viewer for biosynthetic gene cluster data.

You are reading the development README. There are a few other READMEs:

• The README for end-users: backend/README.md (it's the readme of the Python package)
• The README for users of the bgc-viewer-components: frontend/README.md (the readme of the npm package with web components)

Project Structure

The projects consists of a number of modules, which are available in their respective folders as self-contained packages:

• backend: Python Flask server that serves the API and statically built frontend.
• frontend: The frontend folder contains the code for both the web components (npm package) and the viewer as a stand-alone web application (separate build target).

The backend has two functions:

• An API that preprocesses, searches and serves data from a root directory containing huge amounts of data. The backend serves from the local file system in local mode, or from a fixed data directory in public mode see configuration.
• It serves the statically built frontend (html + javascript); the Python package contains everything to run the viewer as a stand-alone application.

The frontend also has multiple functions:

• The BGC Viewer is a web application that can either use the backend API or other data sources.
• The frontend components can be used separately in other applications. They are available as an npm package.

In other words, the frontend can act as a web application with or without the backend. It is packaged with the backend for convenience for end-users, but could perfectly be run in a separate process.

Installation & usage

For end-users, see this README: backend/README.md. For development, a number of different scenarios is possible.

Prerequisites

• Python 3.11+
• uv package manager
• nodejs / npm

Build, install & run all modules

To build both the frontend and the backend, execute the build script from the repository root.

./build.sh

You can then install and run the built Python package as follows (replace {VERSION} with built version):

pip install backend/dist/bgc_viewer-{VERSION}-py3-none-any.whl
bgc-viewer

Frontend development

Although the frontend is served by the backend (Python package) as "static" html/js, it can also be run separately and connect to a running backend API.

cd frontend/

# Install
npm install

# Run dev server
npm run dev

# Build
npm run build

Backend (Python package) development

TODO: some copying of assets from the frontend is required. See ./build.sh script for now.

cd backend/

# Setup environment and install
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Set up configuration if required (see below)

# Run dev server
uv run python -m bgc_viewer.app

# Build
uv build

Configuration

Environment variables can be set to change the configuration of the viewer. A convenient way to change them is to put a file called .env in the directory from which you are running the application.

# Server configuration
BGCV_HOST=localhost              # Server host (default: localhost)
BGCV_PORT=5005                   # Server port (default: 5005)
BGCV_DEBUG_MODE=False            # Enable dev/debug mode (default: False)
BGCV_ALLOWED_ORIGINS=https://yourdomain.com # Allowed CORS origins, relevant when running a public instance
HTTPS_ENABLED=false              # Set to 'true' in production with HTTPS

# Public mode
# In public mode, there won't be an option to access the file system; the database path will be fixed.
# For local development: leave BGCV_PUBLIC_MODE unset or set to 'False'.
# For Docker deployment: BGCV_PUBLIC_MODE is automatically set to 'True' by the Dockerfile (no manual configuration needed).
BGCV_PUBLIC_MODE=False

# In public mode, the DATABASE_PATH and DATA_ROOT below are the locations on the host that will be mounted to fixed
# paths inside the container, i.e. the values are used by docker-compose only.
BGCV_INDEX_DIR=/path/to/index_dir           # Path on the host to the index file directory (used for mounting).
BGCV_DATA_ROOT=/path/to/data_dir            # Path on the host to the data root directory (used for mounting).
BGCV_INDEX_FILENAME=attributes.db           # Name of the index file that is used in public mode.

# Session management
BGCV_SECRET_KEY=your-secret-key             # Required for production - secret key for session signing
REDIS_URL=redis://localhost:6379            # In public mode, this url will be used for session storage
SESSION_DIR=/tmp/sessions                   # Session directory for filesystem storage (fallback)

For more detailed configuration options, see backend/.env.example.

Running the Server

uv run python -m bgc_viewer.app

The server will start on http://localhost:5005 by default.

Code Formatting

# Format code
uv run black bgc_viewer/

# Lint code
uv run flake8 bgc_viewer/

# Type checking
uv run mypy bgc_viewer/

Testing

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=bgc_viewer

License

Apache 2.0