🛠️ Developer Guide

Everything you need to set up, develop, test, and contribute to BioBots Tool.

Prerequisites

Setup

git clone https://github.com/sauravbhattacharya001/BioBots.git
cd BioBots

npm install

start BioBotsTool.sln

Running Locally

Backend (ASP.NET Web API)

The backend runs on IIS Express via Visual Studio. After launching, navigate to the URL shown in the browser (typically http://localhost:{port}/index.html).

Frontend (GitHub Pages Preview)

To preview the docs site locally without the backend, serve the docs/ directory with any static file server:

# Using Python
cd docs
python -m http.server 8080

# Using Node.js (npx)
npx serve docs

# Using PHP
php -S localhost:8080 -t docs

Custom Data File

The backend reads bioprint-data.json from the application root by default. To use a custom path, set DataFilePath in Web.config:

<appSettings>
  <add key="DataFilePath" value="C:\data\my-prints.json" />
</appSettings>

Testing

Run All Tests

npm test

Runs Jest with verbose output and coverage reporting.

Run with Coverage Report

npm run coverage

Generates HTML, LCOV, and JSON coverage reports in the coverage/ directory. Open coverage/index.html in a browser for an interactive report.

Check Coverage Thresholds

npm run coverage:check

Fails if coverage drops below the configured thresholds (70% lines, 60% branches).

Run Specific Test File

# Run only the runMethod tests
npx jest __tests__/runMethod.test.js --verbose

# Run only the comparison tool tests
npx jest __tests__/compare.test.js --verbose

Watch Mode

npx jest --watch

Re-runs tests automatically when source files change.

Test Structure

Adding a New Metric

The backend is designed for easy metric extension. To add a new queryable metric:

public class PrintData
{
    // ... existing properties ...
    
    /// <summary>
    /// Your new metric description.
    /// </summary>
    public double newMetric { get; set; }
}

{ "newMetric", new MetricDescriptor(p => p.print_data.newMetric, isInteger: false) }

Frontend Development

Project Structure

docs/
├── index.html        # Query tool (main page)
├── explorer.html     # Distribution + correlation charts
├── table.html        # Sortable/filterable data table
├── compare.html      # Multi-print comparison with radar chart
├── quality.html      # Quality control scoring dashboard
├── anomaly.html      # Statistical anomaly detector
├── api.html          # API reference documentation
├── architecture.html # Architecture documentation
├── guide.html        # This developer guide
└── bioprint-data.json

Conventions

• Self-contained pages: Each HTML file includes all CSS and JS inline — no build step required
• CSS custom properties: All colors use the :root variables defined at the top
• Canvas rendering: Charts use <canvas> with direct 2D context calls — no charting libraries
• Data loading: Each page loads bioprint-data.json via fetch() on page load
• No build step: Edit HTML files directly and refresh the browser

Adding a New Page

1. Copy an existing page as a template
2. Add the page to the navigation bar in all existing pages
3. Add a nav link in the docs pages sidebar
4. The page will be automatically deployed via the Pages workflow

Docker

Build Locally

docker build -t biobots-tool .
docker run -p 8080:80 biobots-tool

Pull from Registry

docker pull ghcr.io/sauravbhattacharya001/biobots-tool:latest
docker run -p 8080:80 ghcr.io/sauravbhattacharya001/biobots-tool:latest

Custom Data Volume

docker run -p 8080:80 \
  -v /path/to/my-data.json:/app/bioprint-data.json:ro \
  biobots-tool

Contributing

Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests: npm test
5. Commit with a descriptive message
6. Push and open a Pull Request

Code Style

• C#: Follow standard .NET naming conventions. XML doc comments on public members.
• JavaScript: 'use strict' mode. const/let over var. Descriptive function names.
• HTML/CSS: Semantic elements. CSS custom properties for colors. Mobile-responsive.

Commit Messages

Use Conventional Commits format:

feat: add new metric for print speed
fix: handle null crosslinking data
docs: update API reference with examples
test: add coverage for edge cases
chore: update dependencies

Troubleshooting

Common Issues