# Product Requirements Document: BMI Calculator App

## 1. Overview

The BMI Calculator app is a single-page web application that allows users to calculate their Body Mass Index (BMI) by entering their height and weight. The application provides instant BMI calculation results along with health category classification (underweight, normal weight, overweight, obese) and stores calculation history for reference. This tool helps users quickly assess their body mass index and track changes over time.

## 2. User Roles

### Anonymous User (Primary Role)
- Enter height and weight measurements
- Select measurement units (metric or imperial)
- Calculate BMI instantly
- View BMI result and health category
- View calculation history (session-based or persistent)
- Clear calculation history
- Access BMI information and health guidelines

## 3. Core Entities

### Calculation
The primary data object representing a single BMI calculation.
- **id**: Unique identifier for the calculation
- **height**: Height value entered by user
- **weight**: Weight value entered by user
- **heightUnit**: Unit of height measurement (cm, meters, feet/inches)
- **weightUnit**: Unit of weight measurement (kg, lbs)
- **bmiValue**: Calculated BMI result
- **bmiCategory**: Health category classification (underweight, normal, overweight, obese)
- **timestamp**: Date and time when calculation was performed
- **sessionId**: Optional identifier to group calculations by session/user

### BMICategory
Reference data for BMI classification ranges.
- **id**: Unique identifier
- **name**: Category name (Underweight, Normal weight, Overweight, Obese)
- **minBMI**: Minimum BMI value for this category
- **maxBMI**: Maximum BMI value for this category
- **description**: Health information about this category
- **colorCode**: UI color indicator for the category

## 4. Entity Relationships

### Calculation ↔ BMICategory
- **Relationship Type**: Many-to-One
- **Description**: Each Calculation is associated with one BMICategory based on the calculated BMI value. Multiple Calculations can belong to the same BMICategory.
- **Cardinality**: Many Calculations : One BMICategory

### Calculation ↔ Session
- **Relationship Type**: Many-to-One (Optional)
- **Description**: Multiple Calculations can be grouped under a single session identifier for history tracking purposes.
- **Cardinality**: Many Calculations : One Session (implicit grouping)

## 5. Key Workflows

### Workflow 1: Calculate BMI

**Actors**: Anonymous User

**Steps**:
1. User lands on the BMI Calculator page
2. User selects preferred unit system (Metric or Imperial)
3. User enters height value in the input field
4. User enters weight value in the input field
5. User clicks "Calculate BMI" button (or calculation triggers automatically)
6. System validates input values
7. System converts units to standard format if necessary (all to metric for calculation)
8. System calculates BMI using formula: BMI = weight(kg) / (height(m))²
9. System determines BMI category based on calculated value
10. System creates and stores Calculation record
11. System displays BMI result with:
    - Numerical BMI value (rounded to 1 decimal place)
    - Category name with color coding
    - Category description and health information
12. System adds calculation to history list
13. User can view the result and perform another calculation

### Workflow 2: View Calculation History

**Actors**: Anonymous User

**Steps**:
1. User scrolls to or views the history section on the page
2. System retrieves all calculations for the current session
3. System displays calculations in reverse chronological order (newest first)
4. Each history entry shows:
   - Timestamp
   - Height and weight values with units
   - BMI result and category
5. User can review past calculations
6. User can optionally clear individual entries or entire history

### Workflow 3: Clear History

**Actors**: Anonymous User

**Steps**:
1. User clicks "Clear History" button
2. System prompts for confirmation (optional)
3. User confirms action
4. System deletes all calculation records for the current session
5. System updates UI to show empty history state
6. User sees confirmation message

### Workflow 4: Switch Unit Systems

**Actors**: Anonymous User

**Steps**:
1. User toggles between Metric and Imperial unit systems
2. System updates input field labels and placeholders
3. If values are already entered, system converts and displays values in new units
4. User continues with calculation using preferred units

## 6. Features & Requirements

### Module 1: BMI Input Form

**F1.1 Unit System Selection**
- Provide toggle or radio buttons for Metric/Imperial selection
- Default to Metric system
- Metric: Height in cm or m, Weight in kg
- Imperial: Height in feet/inches, Weight in lbs
- Unit selection persists during session

**F1.2 Height Input**
- Numeric input field for height
- Support decimal values
- Metric: Accept cm (0-300) or meters (0-3.0)
- Imperial: Accept feet and inches as separate inputs or combined
- Display appropriate unit label
- Show placeholder with example value
- Real-time validation feedback

**F1.3 Weight Input**
- Numeric input field for weight
- Support decimal values
- Metric: Accept kg (0-500)
- Imperial: Accept lbs (0-1100)
- Display appropriate unit label
- Show placeholder with example value
- Real-time validation feedback

**F1.4 Calculate Button**
- Prominent "Calculate" or "Calculate BMI" button
- Disabled state when inputs are invalid
- Enabled state when all required inputs are valid
- Optional: Auto-calculate on input change (with debounce)
- Visual feedback on click (loading state if needed)

**F1.5 Clear/Reset Button**
- Button to clear all input fields
- Resets form to initial state
- Does not clear history

### Module 2: BMI Result Display

**F2.1 BMI Value Display**
- Show calculated BMI value prominently
- Display as decimal number rounded to 1 decimal place
- Large, readable font size
- Update immediately after calculation

**F2.2 Category Display**
- Show BMI category name clearly
- Color-coded background or text based on category:
  - Underweight: Blue (#3498db)
  - Normal weight: Green (#2ecc71)
  - Overweight: Orange (#f39c12)
  - Obese: Red (#e74c3c)
- Display category icon or visual indicator

**F2.3 Health Information**
- Show description text for the current BMI category
- Provide general health guidance
- Include disclaimer about consulting healthcare professionals
- Display BMI ranges for all categories as reference

**F2.4 Visual Indicator**
- Optional: BMI scale/gauge showing where user's BMI falls
- Optional: Color-coded bar chart with marker
- Visual representation of healthy range

### Module 3: Calculation History

**F3.1 History List Display**
- Display all calculations from current session
- Show most recent calculation first (descending order)
- Each entry includes:
  - Date and time of calculation
  - Height value with unit
  - Weight value with unit
  - BMI result
  - Category with color indicator
- Limit display to last 10-20 calculations
- Responsive layout for mobile devices

**F3.2 History Management**
- "Clear History" button to remove all entries
- Optional: Delete individual history entries
- Confirmation dialog before clearing
- Empty state message when no history exists
- History persists during browser session (sessionStorage or localStorage)

**F3.3 History Export (Optional)**
- Allow users to download history as CSV or PDF
- Include all calculation data in export

### Module 4: Information & Help

**F4.1 BMI Information Section**
- Collapsible or always-visible section explaining BMI
- BMI formula explanation
- BMI category ranges table
- Limitations of BMI as a health metric
- Link to additional health resources

**F4.2 Usage Instructions**
- Brief instructions on how to use the calculator
- Unit conversion tips
- Measurement guidelines (how to measure height/weight accurately)

### Module 5: UI/UX Features

**F5.1 Responsive Design**
- Mobile-first responsive layout
- Works on devices from 320px to 4K displays
- Touch-friendly input controls
- Optimized for portrait and landscape orientations

**F5.2 Accessibility**
- WCAG 2.1 AA compliance
- Keyboard navigation support
- Screen reader compatible
- Sufficient color contrast ratios
- ARIA labels for all interactive elements
- Focus indicators for form inputs

**F5.3 Input Validation**
- Real-time validation with error messages
- Prevent non-numeric input
- Range validation for height and weight
- Clear error messaging
- Visual indicators for valid/invalid states

**F5.4 User Feedback**
- Success message after calculation
- Error messages for invalid inputs
- Loading states for any async operations
- Confirmation dialogs for destructive actions

## 7. Business Rules

### BR1: BMI Calculation Rules
- BMI formula: BMI = weight (kg) / [height (m)]²
- BMI value must be rounded to 1 decimal place
- Minimum calculable BMI: 10.0
- Maximum calculable BMI: 100.0
- Values outside this range should trigger a warning

### BR2: BMI Category Classification
- **Underweight**: BMI < 18.5
- **Normal weight**: BMI 18.5 - 24.9
- **Overweight**: BMI 25.0 - 29.9
- **Obese**: BMI ≥ 30.0
- Categories follow WHO (World Health Organization) standards

### BR3: Input Validation Rules

**Height Validation**:
- Metric (cm): 50 - 300 cm
- Metric (m): 0.5 - 3.0 m
- Imperial: 1'0" - 9'0" (12 - 108 inches)
- Must be positive number
- Maximum 2 decimal places

**Weight Validation**:
- Metric: 10 - 500 kg
- Imperial: 22 - 1100 lbs
- Must be positive number
- Maximum 2 decimal places

### BR4: Unit Conversion Rules
- 1 inch = 2.54 cm
- 1 foot = 12 inches = 30.48 cm
- 1 meter = 100 cm
- 1 kg = 2.20462 lbs
- All conversions maintain 2 decimal precision
- Internal calculations always use metric (kg, meters)

### BR5: History Management Rules
- Maximum 50 calculations stored per session
- Oldest entries automatically removed when limit exceeded
- History cleared on browser close (sessionStorage) OR persists (localStorage)
- Each calculation must have unique timestamp
- Duplicate calculations (same values within 1 minute) allowed

### BR6: Data Persistence Rules
- Calculation history stored in browser storage (localStorage or sessionStorage)
- No server-side persistence required for MVP
- No user authentication required
- No personal data collected beyond calculation inputs
- Storage cleared respects browser privacy settings

### BR7: Display Rules
- All numeric outputs rounded appropriately
- BMI value: 1 decimal place
- Height/Weight in history: match input precision
- Timestamps: Display in user's local timezone
- Use 12-hour or 24-hour format based on locale

## 8. Non-Functional Requirements

### NFR1: Performance
- **Page Load Time**: Initial page load < 2 seconds on 3G connection
- **Calculation Speed**: BMI calculation completes < 100ms
- **Input Responsiveness**: Input validation feedback < 50ms
- **History Rendering**: Display up to 50 history items < 200ms
- **Bundle Size**: Total JavaScript bundle < 100KB (gzipped)
- **Lighthouse Score**: Target 90+ for Performance, Accessibility, Best Practices

### NFR2: Browser Compatibility
- **Modern Browsers**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- **Mobile Browsers**: iOS Safari 14+, Chrome Mobile 90+
- **JavaScript**: ES6+ with appropriate polyfills
- **CSS**: CSS3 with fallbacks for older browsers
- **Storage API**: localStorage/sessionStorage support required

### NFR3: Security
- **Input Sanitization**: All user inputs sanitized to prevent XSS
- **No Sensitive Data**: No PII (Personally Identifiable Information) collected
- **HTTPS**: Application served over HTTPS in production
- **Content Security Policy**: Implement CSP headers
- **No External Data Transmission**: All calculations performed client-side
- **Privacy**: No tracking or analytics without user consent

### NFR4: Scalability
- **Client-Side Only**: No backend infrastructure required for MVP
- **Stateless**: Each calculation independent
- **Storage Limits**: Graceful handling of localStorage quota exceeded
- **Future Backend**: Architecture allows for optional backend integration
- **API-Ready**: Calculation logic can be extracted to API if needed

### NFR5: Accessibility
- **WCAG 2.1 Level AA**: Full compliance required
- **Keyboard Navigation**: All functions accessible via keyboard
- **Screen Readers**: Compatible with JAWS, NVDA, VoiceOver
- **Color Contrast**: Minimum 4.5:1 for normal text, 3:1 for large text
- **Focus Management**: Clear focus indicators, logical tab order
- **ARIA**: Proper ARIA labels, roles, and live regions
- **Text Scaling**: Readable at 200% zoom without horizontal scroll

### NFR6: Usability
- **Intuitive Interface**: No training required to use
- **Error Recovery**: Clear error messages with recovery guidance
- **Consistency**: Consistent UI patterns throughout
- **Feedback**: Immediate feedback for all user actions
- **Mobile-First**: Optimized for touch interactions
- **Loading States**: Visual feedback for any operations > 100ms

### NFR7: Maintainability
- **Code Quality**: ESLint/Prettier configured, 80%+ test coverage
- **Documentation**: Inline code comments, README with setup instructions
- **Component Architecture**: Modular, reusable components
- **State Management**: Clear, predictable state management pattern
- **Version Control**: Git with semantic versioning
- **Build Process**: Automated build and deployment pipeline

### NFR8: Localization (Future)
- **i18n Ready**: Architecture supports internationalization
- **Unit Preferences**: Metric/Imperial based on locale
- **Number Formatting**: Locale-appropriate number formats
- **Date/Time**: Locale-appropriate date/time formats
- **Language**: English for MVP, structure for multi-language support

### NFR9: Reliability
- **Uptime**: 99.9% availability (for hosted version)
- **Error Handling**: Graceful degradation on errors
- **Data Integrity**: Calculation accuracy verified by unit tests
- **Browser Storage**: Handle storage failures gracefully
- **Offline Capability**: Core functionality works offline (PWA consideration)

### NFR10: Monitoring & Analytics (Optional)
- **Error Tracking**: Client-side error logging (e.g., Sentry)
- **Usage Analytics**: Privacy-respecting analytics (opt-in)
- **Performance Monitoring**: Real User Monitoring (RUM)
- **A/B Testing**: Framework for future experimentation

---

## Appendix

### BMI Category Reference Table

| Category | BMI Range | Color Code | Description |
|----------|-----------|------------|-------------|
| Underweight | < 18.5 | #3498db (Blue) | Below healthy weight range |
| Normal weight | 18.5 - 24.9 | #2ecc71 (Green) | Healthy weight range |
| Overweight | 25.0 - 29.9 | #f39c12 (Orange) | Above healthy weight range |
| Obese | ≥ 30.0 | #e74c3c (Red) | Significantly above healthy range |

### Unit Conversion Reference

| From | To | Formula |
|------|-----|---------|
| Pounds (lbs) | Kilograms (kg) | kg = lbs / 2.20462 |
| Kilograms (kg) | Pounds (lbs) | lbs = kg × 2.20462 |
| Inches (in) | Centimeters (cm) | cm = in × 2.54 |
| Centimeters (cm) | Inches (in) | in = cm / 2.54 |
| Feet (ft) | Meters (m) | m = ft × 0.3048 |
| Meters (m) | Feet (ft) | ft = m / 0.3048 |

### Success Metrics

- **User Engagement**: Average calculations per session
- **Completion Rate**: % of users who complete a calculation
- **Error Rate**: % of calculations with validation errors
- **Return Usage**: % of users who perform multiple calculations
- **Mobile Usage**: % of traffic from mobile devices
- **Accessibility Score**: Automated accessibility audit score

---

**Document Version**: 1.0  
**Last Updated**: 2025  
**Document Owner**: Product Management  
**Status**: Ready for Development