Adding a New Bioinformatics Service

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/services/service-info.ts
• src/app/services/(viral-tools)/sars-cov2-genome-analysis/page.tsx
• src/app/services/(viral-tools)/subspecies-classification/page.tsx
• src/components/navbars/navbar-links.ts
• src/app/services/(metagenomics)/taxonomic-classification/page.tsx
• src/app/services/(genomics)/genome-annotation/page.tsx
• src/lib/forms/(viral-tools)/subspecies-classification/subspecies-classification-form-schema.ts

Adding a new bioinformatics service to the DXKB platform involves integrating frontend UI components, form validation logic, and descriptive metadata into a standardized architecture. Each service typically resides within a categorized directory under src/app/services/ (e.g., genomics, metagenomics, viral-tools) and follows a consistent pattern of using TanStack forms for user input and submission.

The integration process requires defining service information for help popups, creating a Zod-based form schema, implementing the service page component, and registering the service in the application's navigation structure. This ensures that the service is discoverable, provides clear instructions to users, and transmits correctly formatted parameters to the backend processing engines.

Architecture and Components

The DXKB service architecture is built on a modular pattern that separates descriptive content from functional logic. A new service integration consists of four primary layers:

1. Metadata Layer: Descriptive content and help documentation.
2. Navigation Layer: Registration of the service in the UI menus.
3. Validation Layer: Schema definitions for input parameters.
4. UI/Interaction Layer: The React page component and form submission hooks.

Service Information and Help Popups

Every service must have a corresponding entry in the global service info repository. This information is used to populate DialogInfoPopup components that explain parameters to users.

Component Property	Description
title	The heading of the help dialog.
description	A high-level summary of the service's function.
sections	Detailed breakdowns of specific parameters (headers and sub-descriptions).

Sources: src/lib/services/service-info.ts:10-50, src/app/services/(viral-tools)/sars-cov2-genome-analysis/page.tsx:210-215

Form Submission Workflow

Services use a standardized submission flow managed by the useServiceFormSubmission hook. This hook handles the transition from UI form values to backend-compatible parameters.

Implementation Steps

1. Define Form Schemas

Services require a Zod schema to enforce data integrity. Common fields include output_path and output_file, which are essential for workspace integration.

export const subspeciesClassificationFormSchema = z.object({
    input_source: inputSourceSchema,
    virus_type: z.string().min(1, "Species is required"),
    output_path: z.string().min(1, "Output folder is required"),
    output_file: z.string().min(1, "Output name is required"),
});

Sources: src/lib/forms/(viral-tools)/subspecies-classification/subspecies-classification-form-schema.ts:40-47

2. Create the Service Page

The service page is a "use client" component that orchestrates UI components. It typically includes:

• ServiceHeader: Displays the title and links to tutorials.
• Card containers: Groups related parameters (e.g., Input Files, Parameters).
• WorkspaceObjectSelector: Allows users to pick files from their DXKB workspace.
• OutputFolder: Handles selection of result destinations.

Sources: src/app/services/(genomics)/genome-annotation/page.tsx:160-250, src/app/services/(viral-tools)/sars-cov2-genome-analysis/page.tsx:230-300

3. Register Navigation Links

The service must be added to serviceItems in the navigation configuration to appear in the top navbar and service menus.

const serviceItems = {
  viralTools: {
    title: "Viral Tools",
    items: [
      {
        title: "SARS-CoV-2 Genome Analysis",
        href: "/services/sars-cov2-genome-analysis",
        target: "_self",
      },
      // New service entry here
    ],
  },
};

Sources: src/components/navbars/navbar-links.ts:133-145

Data Models and Shared Components

Services often utilize shared logic for handling bioinformatics data types, particularly for sequence reads and taxonomy.

Input Libraries

Many services support multiple library types (Paired-end, Single-end, or SRA accessions). The useTanstackLibrarySelection hook is used to manage these collections within the form state.

Library Type	Required Fields	Context
Paired Read	Read 1, Read 2	Standard for Illumina paired sequencing.
Single Read	Read File, Platform	Used for single-end or long-read data (Nanopore).
SRA Accession	SRR ID	Direct download from NCBI SRA.

Sources: src/app/services/(viral-tools)/sars-cov2-genome-analysis/page.tsx:98-115, src/lib/services/service-info.ts:12-40

Taxonomy Integration

For services like Genome Annotation or SARS-CoV-2 Analysis, valid NCBI Taxonomy IDs and names are required. This is facilitated by the TaxonNameSelector and TaxIDSelector components.

Conclusion

Adding a service to DXKB requires adhering to a structured form-based pattern that leverages Zod for validation and standardized React components for workspace interaction. By following the established directory structure and utilizing the shared hooks for parameter transformation and submission, developers ensure that new bioinformatics tools integrate seamlessly with the platform's workspace and job management systems.