Coding Standards & Practices
Relevant source files
The following files were used as context for generating this wiki page:
The DXKB project follows a structured set of coding standards and architectural patterns to ensure maintainability, type safety, and consistent user experiences. The project is built on the Next.js framework, utilizing TypeScript for static typing, Tailwind CSS for styling, and Vitest for testing. Central to its architecture is the separation of form logic, data transformation, and UI presentation.
Key practices include the use of Zod for schema validation, TanStack libraries (Form, Table, and Virtual) for complex data management, and a robust testing suite that verifies utility functions and data transformation logic.
Technical Architecture & Design Patterns
Form Management and Validation
The project utilizes a schema-driven approach to form management. Validation logic is centralized using Zod schemas, which define the structure and constraints of service parameters. This ensures that data is validated on the client side before submission or transformation.
Form validation often includes conditional logic, such as requiring specific input types for unaligned sequences in protein analysis tools.
Sources: src/lib/forms/(protein-tools)/msa-snp-analysis/msa-snp-analysis-form-schema.ts:1-120, src/app/services/(viral-tools)/subspecies-classification/page.tsx:80-95
Data Transformation & Utilities
A consistent pattern in the codebase is the separation of raw form data from the API-ready payload. Utility functions like transformSarsCov2GenomeAnalysisParams handle mapping, default values, and data sanitization.
| Utility Function | Purpose | File Reference |
|---|---|---|
cn | Merges Tailwind classes and handles conditional styling. | src/lib/tests/utils.test.ts:11-23 |
sanitizePathSegment | Removes control characters and null bytes from workspace paths. | src/lib/tests/utils.test.ts:35-57 |
computeOutputName | Joins scientific names and user labels for file generation. | src/lib/forms/(viral-tools)/sars-cov2-genome-analysis/tests/sars-cov2-genome-analysis-form-utils.test.ts:86-105 |
formatElapsedSeconds | Formats job duration (e.g., 65s to "1m5s"). | src/lib/jobs/tests/formatting.test.ts:48-68 |
Frontend & Styling Standards
Tailwind CSS and Theming
Styles are managed via Tailwind CSS with a heavy reliance on a centralized global CSS file that defines theme-specific variables using the oklch color space. The project implements a multi-theme architecture (e.g., zinc, orange, violet, bvbrc) utilizing CSS variables for consistent application of colors, border radii, and ring styles.
Styling follows a "component-first" approach where specific sections (like .funding-section or .team-member) have predefined classes using @apply to maintain consistency across the site.
Sources: src/app/globals.css:1-200, src/styles/theme-content.ts:10-50
Data Presentation
Complex data tables are implemented using @tanstack/react-table. Standards for data display include:
- Virtualization: Using
@tanstack/react-virtualfor high-performance rendering of large datasets. - Sticky Headers: Implementing sticky positions for table headers and pinned columns.
- Controlled State: Managing sorting, pagination, and selection through props to allow parent components to coordinate state.
Sources: src/components/containers/DataTable.tsx:10-150, src/app/globals.css:595-600
Testing Practices
The project maintains high testing standards using Vitest. Test suites are organized to mirror the source structure, typically found in __tests__ directories.
Unit Testing Focus
- Utility Logic: Tests ensure that string manipulation, path normalization, and unit conversions (like file sizes) are accurate.
- Form Utilities: Every service transformation function is tested to ensure it maps form values correctly to API parameters.
- Workspace Helpers: Critical logic regarding permissions (
hasWriteAccess) and path manipulation (normalizeWsPath) is strictly verified.
Project Configuration
The project utilizes pnpm as the package manager and defines strict linting and formatting rules via ESLint and Prettier.
| Category | Tool / Practice | Details |
|---|---|---|
| Scripts | pnpm dev, pnpm test, pnpm lint | Standardized development and CI commands. |
| Dependencies | Next.js, Lucide React, Radix UI | Modern stack prioritizing accessibility and performance. |
| Formatting | Prettier + Tailwind Plugin | Automatic sorting of Tailwind classes in templates. |
| Environment | Turbopack | Enabled for faster local development builds. |
| Sources: package.json:1-120 |
Conclusion
Coding standards in DXKB emphasize a strict contract between data models and the UI. By leveraging schema-based validation, functional data transformations, and centralized styling via CSS variables, the architecture remains robust against changes in service definitions while providing a high-performance interface for complex genomic data analysis. Management of workspace objects and job results follows a predictable pattern of path normalization and permission checking, ensuring security and data integrity.