src/README.md

Source Code Structure

The application has been refactored into a modular structure for better maintainability and debugging.

Directory Structure

src/
├── config.js                    # Application configuration and constants
├── state.js                     # Application state management
├── main.js                      # Main entry point
│
├── models/                      # AI Model management
│   ├── modelLoader.js          # Load and initialize ONNX models
│   ├── inference.js            # Run model predictions
│   └── yoloDetection.js        # YOLO-specific detection logic
│
├── processing/                  # Data processing
│   ├── imagePreprocessing.js   # Image preprocessing for models
│   ├── postprocessing.js       # Model output postprocessing
│   └── yoloPostprocessing.js   # YOLO-specific postprocessing with NMS
│
├── ui/                          # UI components and handlers
│   ├── eventHandlers.js        # Setup all event listeners
│   ├── imageDisplay.js         # Image preview and display
│   ├── loading.js              # Loading overlay controls
│   ├── quickEval.js            # Quick evaluation handlers
│   ├── results.js              # Results display and formatting
│   ├── tabs.js                 # Tab switching logic
│   ├── toast.js                # Toast notifications
│   ├── workflow.js             # Main workflow logic
│   └── zoom.js                 # Zoom controls
│
└── utils/                       # Utility functions
    ├── imageUtils.js           # Image manipulation helpers
    └── mathUtils.js            # Math operations (softmax, etc.)

Module Responsibilities

Core Modules

config.js

• Model paths configuration
• Detection thresholds and parameters
• Label mappings
• ONNX Runtime configuration
• Zoom settings

state.js

• Centralized application state
• State getters and setters
• Current image, models, embryos tracking

main.js

• Application initialization
• Orchestrates model loading
• Sets up event listeners
• Entry point for the app

Model Modules

models/modelLoader.js

• Initialize ONNX Runtime
• Load label mappings from config files
• Load all 4 ONNX models (classifier, quality, grader, YOLO)
• Provide model status

models/inference.js

• Run classification (embryo yes/no)
• Run quality check (poor/good)
• Run grading (Gardner scale)
• Orchestrate full embryo evaluation pipeline

models/yoloDetection.js

• Detect embryos using YOLO model
• Check YOLO availability

Processing Modules

processing/imagePreprocessing.js

• Preprocess images for SigLIP models (224x224)
• Preprocess images for YOLO (640x640)
• Normalize with mean/std

processing/postprocessing.js

• Postprocess classification results
• Postprocess grading results with all predictions
• Apply softmax to logits

processing/yoloPostprocessing.js

• Parse YOLO output format [1, 5, 8400]
• Apply confidence threshold
• Non-Maximum Suppression (NMS)
• Calculate IoU (Intersection over Union)
• Crop detected embryo regions

UI Modules

ui/eventHandlers.js

• Central event listener setup
• Handle image uploads
• Wire up all UI interactions

ui/imageDisplay.js

• Display images in main/quick previews
• Show cropped embryos
• Manage image visibility

ui/loading.js

• Show/hide loading overlay
• Update progress bar
• Display loading messages

ui/quickEval.js

• Quick evaluation workflow
• Clear quick evaluation results

ui/results.js

• Format and display results
• Interpret Gardner grades
• Show top-5 predictions
• Display classification status
• Generate image quality tips

ui/tabs.js

• Switch between main workflow and quick evaluation
• Manage tab state

ui/toast.js

• Show success/error/info toast notifications
• Auto-dismiss after 3 seconds

ui/workflow.js

• Main workflow orchestration
• Classify uploaded images
• Process single/multiple embryo modes
• Navigate between detected embryos
• Evaluate selected embryos

ui/zoom.js

• Adjust zoom level
• Reset zoom
• Apply zoom transform

Utility Modules

utils/imageUtils.js

• Load images from URLs/data URIs
• Crop image regions with padding
• Read files as data URLs

utils/mathUtils.js

• Softmax function
• Mean calculation
• Value clamping

Benefits of Modular Structure

1. Easier Debugging: Each module has a specific responsibility, making it easier to locate and fix bugs
2. Better Testing: Individual modules can be tested in isolation
3. Code Reusability: Functions can be easily imported and reused across different parts of the app
4. Maintainability: Changes to one module don't affect others if interfaces remain stable
5. Readability: Smaller files are easier to understand and navigate
6. Collaboration: Multiple developers can work on different modules simultaneously

How to Add New Features

Adding a New Model

1. Add model path to config.js
2. Load model in models/modelLoader.js
3. Create inference function in models/inference.js
4. Add preprocessing in processing/imagePreprocessing.js if needed
5. Add postprocessing in processing/postprocessing.js

Adding a New UI Component

1. Create new file in ui/ directory
2. Export relevant functions
3. Import and wire up in ui/eventHandlers.js
4. Update main.js if initialization is needed

Modifying Detection Parameters

1. Update thresholds in config.js
2. No code changes needed elsewhere

Import/Export Pattern

All modules use ES6 modules:

// Export
export function myFunction() { ... }
export const myConstant = 42;

// Import
import { myFunction, myConstant } from './module.js';

Debugging Tips

1. Check browser console: All errors are logged with descriptive messages
2. Check Network tab: Verify models are loading correctly
3. Breakpoints: Set breakpoints in specific modules to debug
4. State inspection: Check appState in console to see current state
5. Module isolation: Test individual functions by importing in console

Backup

The original monolithic app.js has been backed up as app.js.backup.