Architecture Overview

Relevant source files

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

• README.md
• package.json
• src/app/layout.tsx
• src/components/navbars/desktop-navbar.tsx
• src/lib/services/workspace/tests/helpers.test.ts
• src/app/(footer)/privacy-policy/data/privacy-policy-sections.ts
• src/styles/theme-content.ts
• src/components/containers/InfoPanel.tsx
• src/app/services/(metagenomics)/metagenomic-binning/page.tsx

The Disease X Knowledge Base (DXKB) is a comprehensive bioinformatics platform designed for scientific research, disease surveillance, and outbreak monitoring. It provides a structured environment for managing viral and bacterial genomic data, running specialized analysis services, and maintaining a private user workspace for research data.

The project is built using the Next.js framework and leverages a backend infrastructure shared with the Bacterial and Viral Bioinformatics Resource Center (BV-BRC). This shared architecture ensures high performance in processing biological data such as genetic codes and protein sequences.

Sources: README.md:1, src/app/(footer)/faq/page.tsx:11-13, src/app/(footer)/privacy-policy/data/privacy-policy-sections.ts:58-65

Frontend Framework and Core Technologies

DXKB is implemented as a modern web application using Next.js 16 and React 19. The application follows a modular structure using the App Router and emphasizes accessibility and customization.

Core Stack

Component	Technology	Description
Framework	Next.js	React-based framework for SSR and client-side routing.
State Management	TanStack Query	Manages server-state and data fetching.
Forms	TanStack Form	Handles complex bioinformatics service parameter inputs.
Authentication	Better Auth	Integrated authentication system.
Styling	Tailwind CSS	Utility-first CSS framework with a custom theming system.
Components	Radix UI	Headless UI components for accessible interface patterns.

Sources: package.json:20-55, src/app/layout.tsx:1-25, README.md:1-5

Application Context and Providers

The root layout wraps the application in several context providers that manage global state:

1. Providers: General wrapper for TanStack Query and global configurations.
2. ThemeProvider: Supports multiple visual themes (zinc, orange, violet, dxkb, bvbrc).
3. AuthProvider: Manages user sessions, profile data from cookies, and authentication state.
4. TooltipProvider: Manages accessible hover tooltips used extensively in complex service forms.

Sources: src/app/layout.tsx:58-85, src/styles/theme-content.ts:4-15

Data and Workspace Architecture

The system utilizes a hierarchical workspace for data management. Users can store reads, contigs, and job results within a structured file system that tracks ownership and permissions.

Workspace Structure

The workspace consists of WorkspaceBrowserItem objects. Every item in the workspace contains critical metadata used for visualization and processing.

Data Access Flow

1. Authentication: Users log in via a shared account system with BV-BRC.
2. Request Handling: Component-based methods (e.g., WorkspaceCrudMethods) delegate requests to the Workspace API (e.g., Workspace.get, Workspace.create).
3. Path Normalization: Internal utilities ensure paths are sanitized (removing null bytes/control characters) and normalized (standardizing slashes) before API interaction.

Sources: src/lib/services/workspace/tests/helpers.test.ts:79-90, src/lib/services/workspace/methods/tests/crud.test.ts:5-15, src/lib/tests/utils.test.ts:37-55

Bioinformatics Service Pipeline

A core feature of the architecture is the ability to submit biological analysis jobs (e.g., Metagenomic Binning, SARS-CoV-2 Genome Analysis).

Service Submission Logic

Services are implemented using a standardized form-to-job pipeline:

1. Form Input: Users select input files (reads or contigs) from the workspace or SRA (Sequence Read Archive).
2. Validation: Zod schemas validate parameters before submission.
3. Transformation: Form values are transformed into a JSON structure compatible with the backend API using utilities like transformMetagenomicBinningParams.
4. Job Tracking: Jobs are queued and progress is tracked in the "Jobs" section of the user workspace.

Theming and Content Mapping

The architecture supports dynamic content and visual styles based on the active theme. This is used to present the application differently depending on the context (e.g., DXKB vs. BV-BRC branding).

Theme Key	Content Folder	Welcome Title (Example)
dxkb	dxkb	Welcome to the Disease X Knowledge Base
bvbrc	bvbrc	Welcome to the Bacterial and Viral Bioinformatics...
zinc/orange	generic	Welcome to the XKnowledge Base

Sources: src/styles/theme-content.ts:16-56

Security and Privacy

The architecture implements strict security measures:

• Access Control: Permissions (o for owner, w for write, r for read) are verified at the helper level before allowing modifications to workspace items.
• Privacy: Private personal information like email is restricted to staff. Usage data is aggregated for reporting to sponsors like CEPI (Coalition for Epidemic Preparedness and Innovation).
• Data Isolation: User research data is not tracked, and access is controlled strictly by the user.

Sources: src/lib/services/workspace/tests/helpers.test.ts:121-140, src/app/(footer)/privacy-policy/data/privacy-policy-sections.ts:4-35

Summary

The DXKB architecture combines a Next.js frontend with the established bioinformatics backend of BV-BRC. It utilizes a centralized workspace model for data management and a standardized submission pipeline for complex bioinformatics tools, all while maintaining strict user permissions and multi-tenant theming capabilities.

Sources: src/app/(footer)/privacy-policy/data/privacy-policy-sections.ts:58-65, src/components/navbars/desktop-navbar.tsx:39-60