# 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 is a lightweight, user-friendly tool designed for quick health assessments without requiring user authentication.

## 2. User Roles

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

## 3. Core Entities

### Calculation
Represents a single BMI calculation performed by a user.

**Attributes:**
- `id` (string/UUID): Unique identifier for the calculation
- `height` (number): Height value entered by user
- `weight` (number): Weight value entered by user
- `heightUnit` (string): Unit of height measurement (cm, m, ft, in)
- `weightUnit` (string): Unit of weight measurement (kg, lbs)
- `bmiValue` (number): Calculated BMI result
- `category` (string): Health category classification
- `timestamp` (datetime): When the calculation was performed

### MeasurementUnit
Defines available measurement systems and units.

**Attributes:**
- `id` (string): Unique identifier
- `system` (string): Measurement system (metric, imperial)
- `heightUnits` (array): Available height units for this system
- `weightUnits` (array): Available weight units for this system
- `defaultHeightUnit` (string): Default height unit
- `defaultWeightUnit` (string): Default weight unit

### BMICategory
Defines BMI ranges and their corresponding health categories.

**Attributes:**
- `id` (string): Unique identifier
- `name` (string): Category name (e.g., "Normal weight")
- `minBMI` (number): Minimum BMI value for this category
- `maxBMI` (number): Maximum BMI value for this category
- `description` (string): Health information for this category
- `colorCode` (string): UI color indicator for the category

## 4. Entity Relationships

### Calculation ↔ MeasurementUnit
- **Relationship Type**: Many-to-One (reference)
- **Description**: Each Calculation references specific measurement units from the MeasurementUnit system
- **Cardinality**: Many Calculations can use the same MeasurementUnit configuration

### Calculation ↔ BMICategory
- **Relationship Type**: Many-to-One (computed)
- **Description**: Each Calculation is classified into one BMICategory based on the calculated BMI value
- **Cardinality**: Many Calculations can belong to the same BMICategory

### MeasurementUnit ↔ BMICategory
- **Relationship Type**: None (independent entities)
- **Description**: These entities operate independently; BMI categories are universal regardless of measurement units

## 5. Key Workflows

### Workflow 1: Calculate BMI

**Actors**: Anonymous User

**Steps**:
1. User lands on the BMI Calculator page
2. System displays default measurement unit system (metric)
3. User selects preferred measurement system (metric or imperial)
4. System updates input fields with appropriate units
5. User enters height value
6. User enters weight value
7. System validates inputs (non-negative, numeric values)
8. User clicks "Calculate" button
9. System converts measurements to standard units if necessary
10. System calculates BMI using formula: BMI = weight(kg) / (height(m))²
11. System determines BMI category based on calculated value
12. System displays BMI result with category and color indicator
13. System adds calculation to history list
14. System displays health information for the category

**Alternative Flows**:
- **5a**: User enters invalid height → System shows validation error
- **6a**: User enters invalid weight → System shows validation error
- **8a**: User submits empty form → System prompts to enter both values

### Workflow 2: View Calculation History

**Actors**: Anonymous User

**Steps**:
1. User performs one or more BMI calculations
2. System stores each calculation in session history
3. User scrolls to history section on the page
4. System displays list of all calculations in reverse chronological order
5. Each history entry shows: timestamp, measurements, BMI value, and category
6. User can review past calculations

### Workflow 3: Clear History

**Actors**: Anonymous User

**Steps**:
1. User views calculation history
2. User clicks "Clear History" button
3. System prompts for confirmation
4. User confirms action
5. System removes all calculations from history
6. System displays empty history state message

### Workflow 4: Switch Measurement Units

**Actors**: Anonymous User

**Steps**:
1. User is on the calculator page with current unit system
2. User clicks unit system toggle (Metric/Imperial)
3. System switches to selected measurement system
4. System updates input field labels and placeholders
5. System clears current input values (if any)
6. User can enter measurements in new unit system

## 6. Features & Requirements

### Module 1: BMI Calculator Form

**FR-1.1**: Display input field for height with unit label
- Support decimal values
- Show placeholder with example value
- Display current unit (cm, m, ft, in)

**FR-1.2**: Display input field for weight with unit label
- Support decimal values
- Show placeholder with example value
- Display current unit (kg, lbs)

**FR-1.3**: Provide measurement system toggle
- Toggle between Metric and Imperial systems
- Visually indicate active system
- Update all related UI elements when switched

**FR-1.4**: Display "Calculate" button
- Enabled only when both inputs are valid
- Show loading state during calculation (if applicable)
- Trigger BMI calculation on click

**FR-1.5**: Support keyboard interactions
- Allow Enter key to submit form
- Tab navigation between fields
- Focus management

### Module 2: Results Display

**FR-2.1**: Display calculated BMI value
- Show value rounded to 1 decimal place
- Display in prominent, readable format
- Include "BMI" label

**FR-2.2**: Display BMI category
- Show category name (e.g., "Normal weight")
- Apply color coding based on category
- Display category description

**FR-2.3**: Show BMI category indicator
- Visual gauge or color bar showing position on BMI scale
- Highlight current category
- Display all category ranges for reference

**FR-2.4**: Provide health information
- Display interpretation of the result
- Show recommended actions or information
- Include disclaimer about consulting healthcare professionals

**FR-2.5**: Display BMI calculation formula
- Show the formula used
- Educational information about BMI
- Collapsible/expandable section

### Module 3: Calculation History

**FR-3.1**: Display history list
- Show all calculations from current session
- Display in reverse chronological order (newest first)
- Limit to most recent 10 calculations

**FR-3.2**: Format history entries
- Show timestamp (relative time: "2 minutes ago")
- Display height and weight with units
- Show BMI value and category
- Apply category color coding

**FR-3.3**: Provide "Clear History" action
- Button to clear all history
- Confirmation dialog before clearing
- Show empty state when no history exists

**FR-3.4**: Persist history in session
- Store history in browser session storage
- Maintain history during page refresh
- Clear history when browser tab/window closes

### Module 4: Unit Conversion

**FR-4.1**: Support metric system
- Height: centimeters (cm) and meters (m)
- Weight: kilograms (kg)
- Default: cm and kg

**FR-4.2**: Support imperial system
- Height: feet (ft) and inches (in)
- Weight: pounds (lbs)
- Default: ft/in and lbs

**FR-4.3**: Perform automatic conversions
- Convert all inputs to metric for calculation
- Conversion formulas:
  - 1 inch = 2.54 cm
  - 1 foot = 30.48 cm
  - 1 pound = 0.453592 kg

**FR-4.4**: Handle compound height input (imperial)
- Allow separate inputs for feet and inches
- Combine values for calculation
- Validate both components

### Module 5: Information & Help

**FR-5.1**: Display BMI category reference table
- Show all BMI ranges and categories
- Include WHO standard classifications
- Color-coded for easy reference

**FR-5.2**: Provide "About BMI" information
- Explanation of what BMI is
- Limitations of BMI as a health metric
- When to consult healthcare professionals

**FR-5.3**: Display disclaimer
- Medical disclaimer about BMI limitations
- Recommendation to consult healthcare provider
- Note about BMI not being suitable for all populations

## 7. Business Rules

### BR-1: BMI Calculation
- BMI formula: `BMI = weight (kg) / (height (m))²`
- Result must be rounded to 1 decimal place
- Calculation only proceeds when both height and weight are valid

### BR-2: BMI Categories (WHO Standard)
- **Underweight**: BMI < 18.5
- **Normal weight**: 18.5 ≤ BMI < 25.0
- **Overweight**: 25.0 ≤ BMI < 30.0
- **Obese**: BMI ≥ 30.0

### BR-3: Input Validation
- Height must be greater than 0
- Weight must be greater than 0
- Height range (metric): 50 cm - 300 cm
- Height range (imperial): 1 ft - 10 ft
- Weight range (metric): 10 kg - 500 kg
- Weight range (imperial): 20 lbs - 1100 lbs
- Only numeric values accepted (including decimals)

### BR-4: Unit Conversion
- All conversions must maintain precision to 2 decimal places during calculation
- Final BMI result rounded to 1 decimal place
- Conversion factors are constants and cannot be modified

### BR-5: History Management
- Maximum 10 calculations stored in history
- When limit exceeded, oldest calculation is removed (FIFO)
- History is session-based (not persistent across browser sessions)
- Each calculation must have a unique timestamp

### BR-6: Measurement System
- Only one measurement system active at a time
- Switching systems clears current input values
- System preference not persisted (defaults to metric on page load)

### BR-7: User Interface
- Calculate button disabled when inputs are invalid or empty
- Error messages displayed inline near relevant input field
- Results only shown after successful calculation
- History section always visible (shows empty state when no calculations)

## 8. Non-Functional Requirements

### NFR-1: Performance
- BMI calculation must complete within 100ms
- Page load time must be under 2 seconds
- UI interactions must respond within 50ms
- No backend API calls required for calculation (client-side only)

### NFR-2: Usability
- Application must be intuitive and require no training
- All text must be readable (WCAG AA contrast standards)
- Form inputs must have clear labels and placeholders
- Error messages must be clear and actionable
- Mobile-friendly responsive design (works on screens 320px and above)

### NFR-3: Accessibility
- WCAG 2.1 Level AA compliance
- Keyboard navigation support for all interactive elements
- Screen reader compatible (proper ARIA labels)
- Focus indicators visible on all interactive elements
- Color not used as the only means of conveying information

### NFR-4: Browser Compatibility
- Support latest 2 versions of Chrome, Firefox, Safari, Edge
- Graceful degradation for older browsers
- No browser-specific features without fallbacks

### NFR-5: Security
- Input sanitization to prevent XSS attacks
- No sensitive data collected or stored
- No external data transmission
- Client-side validation with proper error handling

### NFR-6: Scalability
- Application is stateless (no server-side sessions)
- Can handle unlimited concurrent users (static hosting)
- No database required
- Minimal resource consumption (< 1MB total page weight)

### NFR-7: Maintainability
- Clean, modular code structure
- Comprehensive inline documentation
- Calculation logic separated from UI logic
- Easy to update BMI categories or conversion factors

### NFR-8: Reliability
- Application must work offline after initial load
- No dependencies on external APIs
- Graceful error handling for all edge cases
- Input validation prevents application crashes

### NFR-9: Localization (Future Consideration)
- UI text externalized for easy translation
- Number formatting respects locale
- Date/time formatting respects locale
- Initial version: English only

### NFR-10: Data Privacy
- No personal data collected
- No cookies required
- No analytics tracking (optional, if added must be GDPR compliant)
- Session storage only (automatically cleared)

---

## Appendix: BMI Reference Table

| Category | BMI Range | Color Code |
|----------|-----------|------------|
| Underweight | < 18.5 | Blue (#3B82F6) |
| Normal weight | 18.5 - 24.9 | Green (#10B981) |
| Overweight | 25.0 - 29.9 | Yellow (#F59E0B) |
| Obese | ≥ 30.0 | Red (#EF4444) |

## Appendix: Conversion Formulas

**Length Conversions:**
- Inches to cm: `cm = inches × 2.54`
- Feet to cm: `cm = feet × 30.48`
- Meters to cm: `cm = meters × 100`

**Weight Conversions:**
- Pounds to kg: `kg = pounds × 0.453592`

**BMI Calculation:**
- `BMI = weight_kg / (height_m)²`