Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
177 lines (130 loc) · 4.26 KB

CONTRIBUTING.md

File metadata and controls

177 lines (130 loc) · 4.26 KB
Raw

Contributing — AI Genomics Lab

Guidelines for contributing to the AI Genomics Lab project.

Development Setup

Prerequisites

  • Docker Engine 24+ with Compose v2
  • Python 3.11+ (for local API development)
  • Node.js 20+ (for local frontend development)
  • Git 2.30+

Quick Start

git clone https://github.com/rendergraf/AI-Genomics-Lab.git
cd AI-Genomics-Lab
cp .env.example .env
# Edit .env with your DEEPSEEK_API_KEY or MIMO_API_KEY

# Start all services
cd docker && ./dev.sh start

Development Commands

./dev.sh start        # Start all services
./dev.sh stop         # Stop all services
./dev.sh restart      # Restart all services
./dev.sh logs         # Show all logs
./dev.sh logs-api     # Show API logs
./dev.sh logs-bio     # Show bio-pipeline logs
./dev.sh build        # Build Docker images
./dev.sh rebuild      # Rebuild and start
./dev.sh status       # Show service status
./dev.sh shell-api    # Open shell in API container
./dev.sh shell-bio    # Open shell in bio-pipeline container
./dev.sh clean        # Remove all containers and volumes

Code Standards

Python (API / Services)

  • Python 3.11+ with type hints on all functions
  • Async/await for all database and I/O operations
  • No ORM — use raw SQL with asyncpg for fine-grained control
  • Docstrings on all public functions (Google style)
  • Error handling — never swallow exceptions silently

TypeScript (Frontend)

  • Strict TypeScript — no any types
  • Functional components with hooks
  • Zustand for state management
  • Tailwind CSS for styling (no CSS modules)
  • Storybook stories for all UI components

Bioinformatics

  • Nextflow DSL2 for pipeline definitions
  • Shell scripts with set -e and comprehensive logging
  • Version pinning for all bioinformatics tools in Dockerfile
  • Test mode for all pipelines (configurable read limits)

Git Workflow

Branch Naming

feature/description    — New features
fix/description        — Bug fixes
refactor/description   — Code refactoring
docs/description       — Documentation
test/description       — Test additions

Commit Messages

type(scope): description

Examples:
feat(api): add variant filtering by clinical significance
fix(pipeline): resolve CRAM conversion memory leak
refactor(db): split database_service into repositories
docs(plan): update architecture with production scaling path
test(pipeline): add GIAB benchmark validation script

Pull Request Process

  1. Create feature branch from main
  2. Make changes with clear, atomic commits
  3. Ensure Docker services start cleanly (./dev.sh rebuild)
  4. Test pipeline with sample data
  5. Update documentation if API changes
  6. Create PR with description of changes and testing done

Project Structure Rules

Rule Description
API endpoints Versioned under api/v1/ for clinical data
Services Business logic in services/, not in api/main.py
Database Schema changes via database_service.py migrations
Pipeline Nextflow files in bio-pipeline/, scripts in bio-pipeline/scripts/
Frontend Components in src/components/, pages in src/app/
Tests Test files co-located with source (.spec.ts, .test.py)
Secrets Never commit. Use .env and environment variables

Testing

API Testing

# Run from api/ directory
pip install -r requirements.txt
pytest tests/ -v

Frontend Testing

# Run from frontend/ directory
npm install
npm run test          # Vitest
npm run storybook     # Component testing

Pipeline Testing

# Run inside bio-pipeline container
./dev.sh shell-bio
cd /bio-pipeline

# Test with limited reads
TEST_MODE=true READ_LIMIT=1000 bash scripts/pipeline.sh

Areas for Contribution

High Priority

  • Pipeline validation against GIAB benchmarks
  • ClinVar automated ingestion pipeline
  • Test coverage for API endpoints
  • Performance profiling and optimization

Medium Priority

  • PDF report export
  • Batch analysis support
  • Additional cancer gene panels
  • Frontend accessibility improvements

Documentation

  • API endpoint examples with curl/httpie
  • Pipeline parameter documentation
  • Deployment guide for production
  • Data model documentation