# Product Requirements Document: Utility Calculator

## 1. Overview

The Utility Calculator is a single-page web application that provides users with a comprehensive set of calculation tools for common mathematical, financial, and everyday utility computations. The application offers an intuitive interface where users can select from various calculator types and perform calculations without requiring authentication or data persistence. This tool serves as a quick-access utility for professionals, students, and general users needing reliable calculation capabilities.

## 2. User Roles

### Anonymous User (Default)
- Access all calculator functions without authentication
- Perform unlimited calculations
- View calculation history within the current session
- Copy results to clipboard
- Clear calculation history
- Switch between different calculator types
- No data is saved between sessions

## 3. Core Entities

### Calculator
- **Description**: Represents a specific calculator type/tool available in the application
- **Attributes**:
  - `id` (string): Unique identifier for the calculator
  - `name` (string): Display name of the calculator
  - `description` (string): Brief description of calculator purpose
  - `category` (string): Category grouping (e.g., "Math", "Financial", "Unit Conversion")
  - `icon` (string): Icon identifier for UI display
  - `isActive` (boolean): Whether calculator is currently available

### Calculation
- **Description**: Represents a single calculation operation performed by a user
- **Attributes**:
  - `id` (string): Unique identifier for the calculation
  - `calculatorId` (string): Reference to calculator type used
  - `inputs` (object): Key-value pairs of input parameters
  - `result` (object): Calculated output values
  - `timestamp` (datetime): When calculation was performed
  - `sessionId` (string): Browser session identifier

### CalculatorField
- **Description**: Defines input/output fields for each calculator type
- **Attributes**:
  - `id` (string): Unique identifier
  - `calculatorId` (string): Parent calculator reference
  - `fieldName` (string): Internal field identifier
  - `label` (string): Display label for the field
  - `fieldType` (string): Data type (number, text, select, etc.)
  - `isRequired` (boolean): Whether field is mandatory
  - `validationRules` (object): Validation constraints
  - `defaultValue` (any): Default field value
  - `order` (integer): Display order in UI

### Session
- **Description**: Temporary session data for tracking user activity
- **Attributes**:
  - `sessionId` (string): Unique session identifier
  - `startTime` (datetime): Session start timestamp
  - `lastActivity` (datetime): Last interaction timestamp
  - `calculationCount` (integer): Number of calculations in session

## 4. Entity Relationships

### Calculator ↔ CalculatorField
- **Relationship**: One-to-Many
- **Description**: Each Calculator has multiple CalculatorFields defining its inputs and outputs

### Calculator ↔ Calculation
- **Relationship**: One-to-Many
- **Description**: Each Calculator type can have multiple Calculations performed with it

### Session ↔ Calculation
- **Relationship**: One-to-Many
- **Description**: Each Session contains multiple Calculations performed during that session

## 5. Key Workflows

### Workflow 1: Perform Basic Calculation

1. User lands on the application homepage
2. System displays default calculator (Basic Calculator) with input fields
3. User enters values into input fields
4. System validates inputs in real-time
5. User clicks "Calculate" button or presses Enter
6. System processes calculation using appropriate formula
7. System displays result prominently
8. System adds calculation to session history
9. User can modify inputs and recalculate or clear fields

### Workflow 2: Switch Calculator Type

1. User clicks on calculator selector/dropdown
2. System displays list of available calculators grouped by category
3. User selects desired calculator type
4. System loads selected calculator interface
5. System displays appropriate input fields and labels
6. System clears any previous calculation results
7. User proceeds with new calculation

### Workflow 3: View Calculation History

1. User clicks "History" button/panel
2. System displays list of calculations from current session
3. Each history item shows: calculator type, inputs, result, timestamp
4. User can click on history item to reload those inputs
5. User can clear individual history items or entire history
6. System updates history display in real-time as new calculations are performed

### Workflow 4: Copy Result

1. User completes a calculation
2. System displays result with "Copy" button
3. User clicks "Copy" button
4. System copies result value to clipboard
5. System shows brief confirmation message
6. User can paste result into other applications

## 6. Features & Requirements

### 6.1 Calculator Selection Module

**FR-CS-001**: Display calculator categories in organized navigation
- Categories: Basic Math, Financial, Unit Conversion, Date/Time, Health & Fitness

**FR-CS-002**: Provide search/filter functionality for finding calculators
- Real-time search as user types
- Filter by category

**FR-CS-003**: Show calculator description and use case on hover/selection

**FR-CS-004**: Maintain selected calculator state during session

### 6.2 Basic Math Calculators

**FR-BM-001**: Standard Calculator
- Basic operations: addition, subtraction, multiplication, division
- Advanced operations: square root, power, percentage
- Memory functions: M+, M-, MR, MC
- Keyboard support for number entry and operations

**FR-BM-002**: Scientific Calculator
- Trigonometric functions: sin, cos, tan, arcsin, arccos, arctan
- Logarithmic functions: log, ln
- Constants: π, e
- Degree/Radian mode toggle

**FR-BM-003**: Percentage Calculator
- Calculate percentage of a number
- Calculate what percentage X is of Y
- Calculate percentage increase/decrease
- Add/subtract percentage from number

### 6.3 Financial Calculators

**FR-FN-001**: Loan Calculator
- Inputs: loan amount, interest rate, loan term
- Outputs: monthly payment, total interest, total payment
- Display amortization schedule

**FR-FN-002**: Tip Calculator
- Inputs: bill amount, tip percentage, number of people
- Outputs: tip amount, total per person, total bill

**FR-FN-003**: Currency Converter
- Select source and target currencies
- Real-time exchange rates (or configurable rates)
- Swap currency direction button

**FR-FN-004**: Compound Interest Calculator
- Inputs: principal, rate, time, compounding frequency
- Outputs: final amount, total interest earned
- Visual growth chart

### 6.4 Unit Conversion Calculators

**FR-UC-001**: Length Converter
- Units: meters, kilometers, feet, inches, miles, yards, centimeters

**FR-UC-002**: Weight Converter
- Units: kilograms, grams, pounds, ounces, tons

**FR-UC-003**: Temperature Converter
- Units: Celsius, Fahrenheit, Kelvin

**FR-UC-004**: Volume Converter
- Units: liters, milliliters, gallons, cups, tablespoons, teaspoons

**FR-UC-005**: Area Converter
- Units: square meters, square feet, acres, hectares

### 6.5 Date/Time Calculators

**FR-DT-001**: Date Difference Calculator
- Input two dates
- Output: difference in years, months, days, hours

**FR-DT-002**: Date Add/Subtract Calculator
- Add or subtract days/months/years from a date
- Output: resulting date

**FR-DT-003**: Age Calculator
- Input: birth date
- Output: age in years, months, days

### 6.6 Health & Fitness Calculators

**FR-HF-001**: BMI Calculator
- Inputs: height, weight, unit system (metric/imperial)
- Output: BMI value, category (underweight, normal, overweight, obese)

**FR-HF-002**: Calorie Calculator
- Inputs: age, gender, height, weight, activity level
- Output: daily calorie needs (BMR, TDEE)

### 6.7 Calculation History Module

**FR-CH-001**: Store calculations in browser session storage
- Maximum 50 calculations per session

**FR-CH-002**: Display history panel with toggle visibility

**FR-CH-003**: Show calculation details: type, inputs, result, timestamp

**FR-CH-004**: Allow user to click history item to reload calculation

**FR-CH-005**: Provide "Clear History" button

**FR-CH-006**: Auto-clear history when session expires or browser closes

### 6.8 User Interface Module

**FR-UI-001**: Responsive design supporting desktop, tablet, and mobile

**FR-UI-002**: Single-page application with no page reloads

**FR-UI-003**: Real-time input validation with error messages

**FR-UI-004**: Clear visual feedback for calculation results

**FR-UI-005**: Keyboard shortcuts for common operations

**FR-UI-006**: Accessible design following WCAG 2.1 AA standards

**FR-UI-007**: Dark/Light theme toggle

**FR-UI-008**: Loading indicators for any async operations

### 6.9 Result Display Module

**FR-RD-001**: Display results in large, readable format

**FR-RD-002**: Provide "Copy to Clipboard" functionality

**FR-RD-003**: Show calculation formula/breakdown when applicable

**FR-RD-004**: Format numbers with appropriate decimal places and separators

**FR-RD-005**: Display units with results for unit conversions

## 7. Business Rules

### Validation Rules

**BR-VAL-001**: All numeric inputs must be validated for data type
- Reject non-numeric characters except decimal point and minus sign
- Show error message for invalid input

**BR-VAL-002**: Division by zero must be prevented
- Display error message: "Cannot divide by zero"

**BR-VAL-003**: Required fields must be filled before calculation
- Disable calculate button until all required fields are valid

**BR-VAL-004**: Date inputs must be valid calendar dates
- Reject invalid dates (e.g., February 30)

**BR-VAL-005**: Percentage values must be between 0 and 100 (where applicable)

**BR-VAL-006**: Negative values only allowed where logically appropriate
- Allowed: temperature, financial calculations
- Not allowed: age, weight, distance

### Calculation Rules

**BR-CALC-001**: All calculations must use appropriate precision
- Financial: 2 decimal places
- Scientific: up to 10 decimal places
- Percentages: 2 decimal places

**BR-CALC-002**: Rounding must follow standard mathematical rules
- Round half up for display
- Maintain full precision in intermediate calculations

**BR-CALC-003**: Currency conversions must show exchange rate used

**BR-CALC-004**: BMI categories must follow WHO standards
- Underweight: < 18.5
- Normal: 18.5 - 24.9
- Overweight: 25 - 29.9
- Obese: ≥ 30

### Session Rules

**BR-SESS-001**: Session data stored only in browser (no server persistence)

**BR-SESS-002**: Session expires after 24 hours of inactivity

**BR-SESS-003**: Maximum 50 calculations stored per session
- Oldest calculations removed when limit exceeded

**BR-SESS-004**: No user authentication required for any functionality

### Data Rules

**BR-DATA-001**: No personal data collected or stored on server

**BR-DATA-002**: All calculations performed client-side where possible

**BR-DATA-003**: Exchange rates cached for 1 hour (if using external API)

## 8. Non-Functional Requirements

### Performance

**NFR-PERF-001**: Page load time must be under 2 seconds on 3G connection

**NFR-PERF-002**: Calculation results must display within 100ms of user action

**NFR-PERF-003**: UI interactions must respond within 50ms

**NFR-PERF-004**: Application bundle size must be under 500KB (gzipped)

**NFR-PERF-005**: Support concurrent usage by 10,000+ users without degradation

### Security

**NFR-SEC-001**: All external API calls must use HTTPS

**NFR-SEC-002**: Input sanitization to prevent XSS attacks

**NFR-SEC-003**: Content Security Policy headers implemented

**NFR-SEC-004**: No sensitive data stored in browser storage

**NFR-SEC-005**: Rate limiting on any external API calls (if applicable)

### Scalability

**NFR-SCALE-001**: Application must be stateless to support horizontal scaling

**NFR-SCALE-002**: CDN delivery for static assets

**NFR-SCALE-003**: Client-side rendering to minimize server load

**NFR-SCALE-004**: Lazy loading for calculator modules not immediately needed

### Availability

**NFR-AVAIL-001**: Application uptime of 99.9% (excluding planned maintenance)

**NFR-AVAIL-002**: Graceful degradation if external services unavailable

**NFR-AVAIL-003**: Offline functionality for basic calculators using service workers

### Compatibility

**NFR-COMPAT-001**: Support latest 2 versions of Chrome, Firefox, Safari, Edge

**NFR-COMPAT-002**: Mobile browser support: iOS Safari 13+, Chrome Mobile

**NFR-COMPAT-003**: Progressive Web App (PWA) capabilities

**NFR-COMPAT-004**: Screen reader compatibility

### Usability

**NFR-USE-001**: Maximum 3 clicks to access any calculator

**NFR-USE-002**: Consistent UI patterns across all calculator types

**NFR-USE-003**: Helpful tooltips and placeholder text for all inputs

**NFR-USE-004**: Error messages must be clear and actionable

**NFR-USE-005**: Support for keyboard-only navigation

### Maintainability

**NFR-MAINT-001**: Modular architecture allowing easy addition of new calculators

**NFR-MAINT-002**: Comprehensive unit test coverage (minimum 80%)

**NFR-MAINT-003**: Documented API for calculation functions

**NFR-MAINT-004**: Logging for errors and usage analytics

### Monitoring

**NFR-MON-001**: Track calculator usage metrics (which calculators used most)

**NFR-MON-002**: Monitor error rates and types

**NFR-MON-003**: Track performance metrics (load time, calculation time)

**NFR-MON-004**: Anonymous usage analytics (no PII)

### Localization

**NFR-LOCAL-001**: Support for number formatting based on locale

**NFR-LOCAL-002**: Date formatting based on locale

**NFR-LOCAL-003**: Decimal separator handling (comma vs period)

**NFR-LOCAL-004**: Prepared for multi-language support (English as initial language)

---

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