Service Form Architecture

Relevant source files

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

• src/hooks/services/use-service-form-submission.ts
• src/app/services/(genomics)/genome-annotation/page.tsx
• src/app/services/(genomics)/variation-analysis/page.tsx
• src/app/services/(viral-tools)/sars-cov2-genome-analysis/page.tsx
• src/app/services/(genomics)/blast/page.tsx
• src/lib/services/service-info.ts
• src/hooks/services/use-rerun-form.ts

The Service Form Architecture in the DXKB project provides a standardized framework for capturing biological parameters, validating user input, and submitting bioinformatics jobs to the backend application service. It leverages a modern React stack, primarily utilizing @tanstack/react-form for state management, zod for schema validation, and custom hooks to bridge the gap between UI components and the job submission API.

This architecture is designed to handle diverse analytical tools—ranging from Genome Annotation and Variation Analysis to BLAST searches—ensuring a consistent user experience while accommodating tool-specific parameter requirements.

Core Architecture Components

The architecture is built upon a modular design where individual service pages (e.g., GenomeAnnotationContent, VariationAnalysisPage) compose shared components and hooks to manage complex form states.

Form State Management and Validation

Each service utilizes the useForm hook from @tanstack/react-form to manage its internal state. Validation is enforced through Zod schemas that define the structure and constraints of the data before it can be submitted.

Component/Hook	Role	Key File References
useForm	Manages field values, validation states, and submission logic.	genome-annotation/page.tsx:64
useStore	Subscribes to specific form values to trigger UI updates (e.g., output path validation).	variation-analysis/page.tsx:151
Zod Schemas	Defines data types and business rules (e.g., completeGenomeAnnotationSchema).	genome-annotation/page.tsx:50

Submission Orchestration

The useServiceFormSubmission hook serves as the central orchestrator for job submission. It handles the transformation of UI-friendly form data into the specific JSON parameters required by the backend, manages submission loading states, and provides debugging capabilities via a "Job Parameters" dialog.

Data Flow: From Form to Job Submission

The data flow follows a strict pipeline: User Input -> Form State -> Parameter Transformation -> API Request.

Parameter Transformation

Because the backend often requires specific keys or data structures that differ from the UI's flat form structure, each service implements a transformParams function. For example, transformVariationAnalysisParams converts the UI's library selection into the structured format required by the variation service.
Sources: variation-analysis/page.tsx:129, blast/page.tsx:65

Job Rerunning and Pre-filling

The useRerunForm hook allows the architecture to "hydrate" form state from previous job parameters. This is critical for the "Rerun" feature, where a user can load settings from a completed job into a new form session.

Shared UI Infrastructure

Forms are constructed using a set of reusable UI components tailored for bioinformatics workflows.

1. Service Headers and Information Popups

The ServiceHeader and DialogInfoPopup components provide contextual help and metadata for each tool. These components pull descriptive text from a centralized service-info.ts configuration file.
Sources: service-header.tsx:21, service-info.ts:1-10

2. Workspace Integration

Specialized selectors like WorkspaceObjectSelector and OutputFolder allow users to interact with their DXKB workspace to select input files (reads, contigs, fasta) and define destination folders for results.
Sources: genome-annotation/page.tsx:187, blast/page.tsx:442

3. Library Selection Logic

For services involving sequencing reads (e.g., SARS-CoV-2 Analysis, Variation Analysis), the useTanstackLibrarySelection hook manages the complexity of adding/removing paired-end libraries, single-end libraries, and SRA run accessions.

Feature	Description	File Reference
Paired Library	Requires two files (Read 1 and Read 2).	variation-analysis/page.tsx:186
SRA Accession	Validates NCBI SRR numbers before adding to the job.	sars-cov2-genome-analysis/page.tsx:327
Platform Support	Supports selecting sequencing platforms (Illumina, Nanopore, etc).	sars-cov2-genome-analysis/page.tsx:345

Implementation Example: BLAST Service

The BLAST service page (blast/page.tsx) demonstrates the architecture's ability to handle dynamic UI based on selected programs. It tracks the blast_program and clears incompatible input fields when the program changes (e.g., switching from protein to nucleotide search).
Sources: blast/page.tsx:155-171

Conclusion

The Service Form Architecture provides a robust, type-safe, and highly reusable foundation for DXKB's analytical tools. By separating UI state (TanStack Form), validation (Zod), and API logic (useServiceFormSubmission), the project maintains a clear path for adding new services while ensuring that complex logic like parameter transformation and job rerunning remains maintainable across the codebase.