# Product Requirements Document: Simple Interest Calculator

## 1. Overview

The Simple Interest Calculator is a single-page web application that enables users to calculate simple interest on principal amounts over specified time periods. The application provides an intuitive interface for inputting loan or investment parameters and instantly displays calculated interest and total amount. This tool serves individuals, students, and financial professionals who need quick, accurate simple interest calculations without complex financial software.

## 2. User Roles

### Anonymous User (Default Role)
- Access the calculator interface without authentication
- Input principal amount, interest rate, and time period
- View calculated simple interest and total amount
- Clear/reset calculator inputs
- View calculation history within current session
- No data persistence across sessions

## 3. Core Entities

### Calculation
**Description:** Represents a single simple interest calculation performed by a user.

**Attributes:**
- `id` (string, UUID): Unique identifier for the calculation
- `principal` (number, decimal): The initial amount of money (loan or investment)
- `rate` (number, decimal): Annual interest rate as a percentage
- `time` (number, decimal): Time period in years
- `interest` (number, decimal): Calculated simple interest amount
- `totalAmount` (number, decimal): Principal + Interest
- `timestamp` (datetime): When the calculation was performed
- `sessionId` (string): Browser session identifier for grouping calculations

## 4. Entity Relationships

### Calculation Relationships
- **Session to Calculations**: One-to-Many
  - A single browser session can have multiple calculations
  - Calculations are grouped by `sessionId` for session-based history
  - No cross-session data access (session-scoped only)

## 5. Key Workflows

### Workflow 1: Perform Simple Interest Calculation

1. User lands on the calculator page
2. System generates/retrieves session identifier
3. User enters principal amount in the input field
4. User enters annual interest rate (as percentage)
5. User enters time period in years
6. User clicks "Calculate" button
7. System validates all inputs (see Business Rules)
8. System calculates simple interest using formula: `I = P × R × T / 100`
9. System calculates total amount: `A = P + I`
10. System creates Calculation entity with all values
11. System stores calculation in session history
12. System displays results:
    - Simple Interest amount
    - Total Amount (Principal + Interest)
    - Breakdown of calculation
13. Calculation is added to session history list

### Workflow 2: View Calculation History

1. User performs one or more calculations (Workflow 1)
2. System maintains list of calculations for current session
3. User views history section on the same page
4. System displays list of previous calculations showing:
   - Principal, Rate, Time inputs
   - Calculated Interest and Total Amount
   - Timestamp of calculation
5. History is ordered by most recent first
6. History persists only for current browser session

### Workflow 3: Clear/Reset Calculator

1. User clicks "Clear" or "Reset" button
2. System clears all input fields
3. System clears displayed results
4. System retains calculation history
5. Calculator returns to initial empty state

### Workflow 4: Clear History

1. User clicks "Clear History" button
2. System prompts for confirmation
3. User confirms action
4. System removes all calculations from session history
5. History section displays empty state
6. Current calculation inputs/results remain unchanged

## 6. Features & Requirements

### Module 1: Calculator Interface

**F1.1 Input Form**
- Display input field for Principal Amount with currency symbol ($)
- Display input field for Interest Rate with percentage symbol (%)
- Display input field for Time Period with unit selector (years/months)
- All fields must accept decimal values
- Provide clear labels for each input field
- Display placeholder text with example values
- Support keyboard navigation (tab order)

**F1.2 Time Unit Conversion**
- Provide dropdown/toggle to select time unit (Years or Months)
- When "Months" selected, convert months to years for calculation (divide by 12)
- Display selected unit next to time input field
- Default unit is "Years"

**F1.3 Action Buttons**
- "Calculate" button (primary action, enabled when all fields valid)
- "Clear" button (secondary action, always enabled)
- Buttons must be clearly labeled and visually distinct
- Display loading state during calculation (if needed)

**F1.4 Results Display**
- Show calculated Simple Interest with currency formatting
- Show Total Amount (Principal + Interest) with currency formatting
- Display calculation breakdown/formula used
- Show all input values used in the calculation
- Highlight results with visual distinction from inputs
- Results appear immediately below the calculator form

**F1.5 Real-time Validation**
- Display inline validation messages for invalid inputs
- Highlight invalid fields with visual indicators (red border)
- Disable "Calculate" button when inputs are invalid
- Show validation messages below respective fields

### Module 2: Calculation History

**F2.1 History List Display**
- Display list of all calculations from current session
- Show maximum of 10 most recent calculations
- Each history item displays:
  - Principal amount
  - Interest rate
  - Time period (with unit)
  - Calculated interest
  - Total amount
  - Timestamp (relative time: "2 minutes ago")
- History items are collapsible/expandable for space efficiency

**F2.2 History Management**
- "Clear History" button above history list
- Confirmation dialog before clearing history
- Empty state message when no history exists
- History automatically updates when new calculation is performed

**F2.3 History Interaction**
- Click on history item to load those values back into calculator
- Visual hover state for history items
- Smooth scroll to calculator when history item is clicked

### Module 3: Calculation Engine

**F3.1 Simple Interest Calculation**
- Implement formula: `Simple Interest = (Principal × Rate × Time) / 100`
- Implement formula: `Total Amount = Principal + Simple Interest`
- Support decimal precision up to 2 decimal places for currency
- Round results using standard rounding rules (0.5 rounds up)

**F3.2 Input Processing**
- Parse string inputs to numerical values
- Handle comma-separated numbers (e.g., "1,000")
- Trim whitespace from inputs
- Convert time from months to years when applicable

### Module 4: User Interface/UX

**F4.1 Layout & Design**
- Single-page responsive layout
- Calculator centered on page
- History section positioned below or beside calculator
- Clean, minimal design with clear visual hierarchy
- Adequate spacing between elements
- Mobile-friendly responsive design (breakpoints for tablet/mobile)

**F4.2 Accessibility**
- All form inputs have associated labels
- ARIA labels for screen readers
- Keyboard navigation support
- Sufficient color contrast (WCAG AA compliance)
- Focus indicators on interactive elements

**F4.3 Visual Feedback**
- Success state when calculation completes
- Error states for validation failures
- Hover states for interactive elements
- Smooth transitions for showing/hiding elements
- Loading indicators if needed

## 7. Business Rules

### BR1: Input Validation Rules

**BR1.1 Principal Amount**
- Must be a positive number greater than 0
- Maximum value: 999,999,999.99
- Must not be empty
- Can include up to 2 decimal places
- Error message: "Principal must be a positive number greater than 0"

**BR1.2 Interest Rate**
- Must be a positive number greater than 0
- Maximum value: 100 (representing 100%)
- Must not be empty
- Can include up to 2 decimal places
- Error message: "Interest rate must be between 0 and 100"

**BR1.3 Time Period**
- Must be a positive number greater than 0
- Maximum value: 100 years (or 1200 months)
- Must not be empty
- Can include up to 2 decimal places
- Error message: "Time period must be greater than 0"

### BR2: Calculation Rules

**BR2.1 Formula Application**
- Simple Interest formula must always be: I = (P × R × T) / 100
- Where P = Principal, R = Rate (annual %), T = Time (in years)
- Total Amount = Principal + Simple Interest

**BR2.2 Precision & Rounding**
- All monetary values must be rounded to 2 decimal places
- Use standard rounding: 0.5 and above rounds up
- Display currency with appropriate symbol and formatting

**BR2.3 Time Conversion**
- When time unit is "Months", divide by 12 to convert to years
- Conversion formula: Years = Months / 12
- Maintain precision during conversion

### BR3: Session & History Rules

**BR3.1 Session Management**
- Each browser session gets unique session identifier
- Session persists until browser tab/window is closed
- No data shared between different browser sessions
- Session ID generated on first page load

**BR3.2 History Limitations**
- Maximum 10 calculations stored per session
- When limit reached, oldest calculation is removed (FIFO)
- History cleared when user explicitly clears it
- History not persisted to server or local storage (session memory only)

### BR4: Data Constraints

**BR4.1 Numerical Constraints**
- All calculations must use decimal/float data types
- Prevent integer overflow by enforcing maximum values
- Handle division by zero (not applicable in this calculator)
- Prevent negative values in all inputs

**BR4.2 Display Constraints**
- Currency values display with 2 decimal places
- Percentages display with up to 2 decimal places
- Large numbers formatted with thousand separators (e.g., 1,000.00)
- Timestamps display in user-friendly relative format

## 8. Non-Functional Requirements

### NFR1: Performance

**NFR1.1 Response Time**
- Calculation must complete within 100ms
- Page initial load time under 2 seconds
- Input validation feedback within 50ms
- History list rendering under 200ms

**NFR1.2 Resource Usage**
- Application bundle size under 500KB (compressed)
- Memory usage under 50MB for session with 10 calculations
- Minimal CPU usage during idle state

### NFR2: Security

**NFR2.1 Input Sanitization**
- Sanitize all user inputs to prevent XSS attacks
- Validate input types on both client and server (if applicable)
- Prevent script injection through input fields

**NFR2.2 Data Privacy**
- No personal data collected or stored
- No tracking or analytics without user consent
- Session data stored only in browser memory (not cookies or local storage)
- No server-side data persistence

### NFR3: Scalability

**NFR3.1 Client-Side Scalability**
- Application must function entirely client-side
- No backend API required for core functionality
- Support concurrent usage by multiple users (each with own session)
- Handle up to 10 calculations per session without performance degradation

### NFR4: Compatibility

**NFR4.1 Browser Support**
- Support latest 2 versions of Chrome, Firefox, Safari, Edge
- Graceful degradation for older browsers
- No browser-specific features that break cross-compatibility

**NFR4.2 Device Support**
- Fully responsive design for desktop (1920px+)
- Tablet support (768px - 1024px)
- Mobile support (320px - 767px)
- Touch-friendly interface for mobile devices

**NFR4.3 Accessibility**
- WCAG 2.1 Level AA compliance
- Screen reader compatible
- Keyboard navigation support
- Minimum font size 14px for readability

### NFR5: Usability

**NFR5.1 User Experience**
- Intuitive interface requiring no training
- Clear error messages with actionable guidance
- Consistent visual design language
- Maximum 3 clicks to complete any task

**NFR5.2 Learnability**
- First-time users can complete calculation within 30 seconds
- Tooltips or help text for complex fields (if any)
- Example values in placeholders

### NFR6: Maintainability

**NFR6.1 Code Quality**
- Modular, component-based architecture
- Clear separation of concerns (UI, business logic, data)
- Comprehensive inline code documentation
- Follow industry-standard coding conventions

**NFR6.2 Testing**
- Unit test coverage for calculation logic (minimum 80%)
- Integration tests for key workflows
- Cross-browser testing for compatibility
- Accessibility testing with automated tools

### NFR7: Reliability

**NFR7.1 Error Handling**
- Graceful handling of invalid inputs
- User-friendly error messages
- No application crashes or unhandled exceptions
- Fallback UI for unexpected errors

**NFR7.2 Data Integrity**
- Calculation results must be mathematically accurate
- No data loss during session
- Consistent state management

---

## Appendix: Calculation Formula Reference

**Simple Interest Formula:**
```
Simple Interest (I) = (P × R × T) / 100

Where:
P = Principal Amount
R = Annual Interest Rate (as percentage)
T = Time Period (in years)

Total Amount (A) = P + I
```

**Example Calculation:**
```
Principal: $10,000
Rate: 5% per annum
Time: 2 years

Simple Interest = (10,000 × 5 × 2) / 100 = $1,000
Total Amount = 10,000 + 1,000 = $11,000
```