# 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., "Underweight", "Normal weight")
- `minBMI` (number): Minimum BMI value for this category
- `maxBMI` (number): Maximum BMI value for this category
- `description` (string): Health information about this category
- `colorCode` (string): UI color indicator for this 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.

### Calculation ↔ MeasurementUnit
- **Relationship Type:** Many-to-One (implicit)
- **Description:** Each Calculation references measurement units from the MeasurementUnit entity. The heightUnit and weightUnit fields in Calculation correspond to units defined in MeasurementUnit.

### Session ↔ Calculation
- **Relationship Type:** One-to-Many (session-based)
- **Description:** A single browser session can contain multiple Calculations. Calculations are stored in browser session/local storage and associated with the current session.

## 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
14. System persists calculation to browser storage

**Success Criteria:**
- BMI is calculated accurately
- Correct category is displayed
- Calculation appears in history

**Error Scenarios:**
- Invalid input (non-numeric): Display error message
- Missing height or weight: Display validation message
- Negative values: Display error message

### Workflow 2: View Calculation History

**Actors:** Anonymous User

**Steps:**
1. User performs one or more BMI calculations
2. System displays history section below calculator
3. System shows list of previous calculations in reverse chronological order
4. Each history entry displays: timestamp, height, weight, BMI value, category
5. User can scroll through history if multiple entries exist

**Success Criteria:**
- All calculations from current session are visible
- Most recent calculation appears first
- Each entry shows complete information

### 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 storage
6. System clears history display
7. System shows empty state message

**Success Criteria:**
- All history entries are removed
- Storage is cleared
- Empty state is displayed

### Workflow 4: Switch Measurement Units

**Actors:** Anonymous User

**Steps:**
1. User is on BMI Calculator page
2. User clicks measurement unit toggle/selector
3. System switches between metric and imperial
4. System updates input field labels and placeholders
5. System clears previous input values (optional) or converts them
6. User can now enter values in new unit system

**Success Criteria:**
- Unit labels update correctly
- Input fields reflect new units
- Calculation works with new units

## 6. Features & Requirements

### Module 1: BMI Calculator Form

#### F1.1: Measurement Unit Selection
- Display toggle or dropdown for measurement system selection
- Support metric system (kg, cm/m)
- Support imperial system (lbs, ft/in)
- Persist selected unit preference in session
- Default to metric system on first visit

#### F1.2: Height Input
- Provide numeric input field for height
- Display appropriate unit label based on selected system
- Support decimal values
- Show placeholder with example value
- Validate input in real-time
- Accept height in cm (metric) or feet/inches (imperial)

#### F1.3: Weight Input
- Provide numeric input field for weight
- Display appropriate unit label based on selected system
- Support decimal values
- Show placeholder with example value
- Validate input in real-time
- Accept weight in kg (metric) or lbs (imperial)

#### F1.4: Calculate Button
- Display prominent "Calculate" button
- Enable only when valid inputs are provided
- Trigger BMI calculation on click
- Show loading state during calculation (if applicable)
- Support Enter key submission

#### F1.5: Clear/Reset Button
- Provide button to clear all input fields
- Reset form to initial state
- Do not clear calculation history

### Module 2: Results Display

#### F2.1: BMI Value Display
- Show calculated BMI value prominently
- Display value rounded to 1 decimal place
- Use large, readable font
- Include "BMI" label

#### F2.2: Category Display
- Show health category name
- Display category description
- Use color coding for visual indication:
  - Underweight: Blue (#3B82F6)
  - Normal weight: Green (#10B981)
  - Overweight: Orange (#F59E0B)
  - Obese: Red (#EF4444)
- Show category range (e.g., "18.5 - 24.9")

#### F2.3: Health Information
- Display brief explanation of BMI result
- Show recommended actions or considerations
- Include disclaimer about BMI limitations
- Provide link to detailed health information (optional)

### Module 3: Calculation History

#### F3.1: History List
- Display all calculations from current session
- Show entries in reverse chronological order (newest first)
- Limit display to last 10 calculations
- Each entry includes:
  - Timestamp (formatted as "MMM DD, YYYY HH:MM AM/PM")
  - Height with unit
  - Weight with unit
  - BMI value
  - Category badge with color

#### F3.2: History Management
- Provide "Clear History" button
- Show confirmation dialog before clearing
- Display empty state when no history exists
- Persist history in browser local storage

#### F3.3: History Item Actions
- Allow deletion of individual history entries
- Support clicking entry to repopulate calculator form (optional)

### Module 4: Information & Help

#### F4.1: BMI Information Panel
- Display "What is BMI?" section
- Explain BMI formula
- Show BMI category ranges table
- Include health guidelines

#### F4.2: Disclaimer
- Display medical disclaimer
- Note that BMI is a screening tool, not diagnostic
- Recommend consulting healthcare provider
- Mention BMI limitations (muscle mass, age, etc.)

### Module 5: User Interface

#### F5.1: Responsive Design
- Support mobile devices (320px and up)
- Support tablets (768px and up)
- Support desktop (1024px and up)
- Adapt layout for different screen sizes
- Ensure touch-friendly controls on mobile

#### F5.2: Accessibility
- Support keyboard navigation
- Include ARIA labels for screen readers
- Maintain sufficient color contrast (WCAG AA)
- Provide focus indicators
- Support text scaling

#### F5.3: Visual Design
- Clean, modern interface
- Clear visual hierarchy
- Consistent spacing and typography
- Intuitive iconography
- Professional color scheme

## 7. Business Rules

### BR1: BMI Calculation
- BMI formula: `BMI = weight (kg) / (height (m))²`
- Result must be rounded to 1 decimal place
- Minimum acceptable BMI: 10.0
- Maximum acceptable BMI: 100.0

### BR2: BMI Categories
- **Underweight:** BMI < 18.5
- **Normal weight:** BMI 18.5 - 24.9
- **Overweight:** BMI 25.0 - 29.9
- **Obese:** BMI ≥ 30.0

### BR3: 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.5 ft - 9 ft
- Weight range (metric): 10 kg - 500 kg
- Weight range (imperial): 20 lbs - 1100 lbs
- Only numeric values accepted (including decimals)

### BR4: Unit Conversions
- 1 inch = 2.54 cm
- 1 foot = 12 inches = 30.48 cm
- 1 meter = 100 cm
- 1 pound = 0.453592 kg
- Conversions must maintain precision to 2 decimal places

### BR5: History Management
- Maximum 100 calculations stored per session
- Oldest entries automatically removed when limit exceeded
- History persists across page refreshes (local storage)
- History cleared when browser storage is cleared
- Each calculation must have unique timestamp

### BR6: Data Persistence
- Use browser localStorage for history persistence
- Storage key: `bmi_calculator_history`
- Data format: JSON array
- Handle storage quota exceeded gracefully
- Validate stored data on retrieval

### BR7: Error Handling
- Display user-friendly error messages
- Validate inputs before calculation
- Handle division by zero
- Handle invalid stored data
- Provide fallback for unsupported browsers

## 8. Non-Functional Requirements

### NFR1: Performance
- Page load time: < 2 seconds on 3G connection
- BMI calculation: < 100ms response time
- History rendering: < 200ms for 100 entries
- Smooth animations: 60fps
- Minimal JavaScript bundle size: < 100KB (gzipped)

### NFR2: Browser Compatibility
- Support Chrome (last 2 versions)
- Support Firefox (last 2 versions)
- Support Safari (last 2 versions)
- Support Edge (last 2 versions)
- Graceful degradation for older browsers

### NFR3: Security
- No sensitive data collection
- No external API calls required
- Client-side only calculations
- Sanitize all user inputs
- Prevent XSS attacks
- No cookies required

### NFR4: Scalability
- Pure client-side application (no backend required)
- Can be hosted on static file server
- CDN-friendly architecture
- No database required
- Stateless design

### NFR5: Reliability
- 99.9% uptime (dependent on hosting)
- Graceful handling of localStorage failures
- No data loss during calculation
- Consistent calculation results
- Fallback for missing browser features

### NFR6: Usability
- Intuitive interface requiring no instructions
- Calculation completable in < 30 seconds
- Clear error messages
- Immediate visual feedback
- No learning curve required

### NFR7: Accessibility (WCAG 2.1 Level AA)
- Keyboard navigable
- Screen reader compatible
- Color contrast ratio ≥ 4.5:1 for text
- Focus indicators visible
- Alt text for all images/icons
- Semantic HTML structure

### NFR8: Maintainability
- Clean, documented code
- Modular component structure
- Separation of concerns
- Unit test coverage > 80%
- Clear naming conventions
- Version control friendly

### NFR9: Localization (Future Consideration)
- Support for multiple languages
- Locale-specific number formatting
- Date/time formatting per locale
- RTL language support
- Unit system defaults by region

### NFR10: Analytics & Monitoring
- Track calculation events (optional)
- Monitor error rates
- Track measurement system preference
- No personally identifiable information (PII) collected
- Privacy-compliant analytics only

---

## Appendix

### BMI Category Reference Table

| Category | BMI Range | Color Code | Description |
|----------|-----------|------------|-------------|
| Underweight | < 18.5 | #3B82F6 (Blue) | Below healthy weight range |
| Normal weight | 18.5 - 24.9 | #10B981 (Green) | Healthy weight range |
| Overweight | 25.0 - 29.9 | #F59E0B (Orange) | Above healthy weight range |
| Obese | ≥ 30.0 | #EF4444 (Red) | Significantly above healthy weight |

### Conversion Formulas

**Height Conversions:**
- Feet to meters: `feet × 0.3048`
- Inches to meters: `inches × 0.0254`
- Centimeters to meters: `cm ÷ 100`

**Weight Conversions:**
- Pounds to kilograms: `lbs × 0.453592`

**BMI Formula:**
```
BMI = weight_kg / (height_m)²
```

### Sample Calculations

**Example 1 (Metric):**
- Height: 175 cm (1.75 m)
- Weight: 70 kg
- BMI: 70 / (1.75)² = 22.9
- Category: Normal weight

**Example 2 (Imperial):**
- Height: 5 ft 9 in (1.753 m)
- Weight: 154 lbs (69.85 kg)
- BMI: 69.85 / (1.753)² = 22.7
- Category: Normal weight

---

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