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:
```javascript
// 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`.