# Battery Tracker - Functional Specification Document

## 1. Overview

Battery Tracker is a personal web application designed to help users manage their rechargeable battery inventory. It solves the common problem of losing track of batteries that are placed in rarely-used devices.

## 2. Problem Statement

Users with multiple rechargeable batteries often:
- Forget which device contains which batteries
- Cannot quickly determine how many batteries are available
- Lose track of batteries currently being charged
- Have no centralized way to manage battery inventory

## 3. Core Features

### 3.1 Battery Type Management
- Define battery form factors (AA, AAA, 18650, CR2032, etc.)
- Define battery chemistries (NiMH, Li-ion, LiFePO4, etc.)
- Associate brands with battery types and chemistries
- Track total quantity per brand-type-chemistry combination

### 3.2 Battery Status Tracking
Each brand-type-chemistry combination can have batteries in three states:

| Status | Description |
|--------|-------------|
| **Available** | Batteries in storage, ready for use |
| **In Use** | Batteries currently placed in a device |
| **Charging** | Batteries currently being recharged |

### 3.3 Device Management
- Create and manage a list of devices (keyboard, mouse, remote, flashlight, etc.)
- Assign batteries to devices with quantity
- Quick view of which device has which batteries

### 3.4 Quick Actions
- Move batteries between states (Available -> In Use -> Charging -> Available)
- Batch operations for multiple batteries
- Quick "return to storage" action when removing from device

### 3.5 Dashboard
- Overview of all battery inventory
- Quick status summary (X available, Y in use, Z charging)
- Low stock alerts (optional)

## 4. User Stories

### US-01: Add Battery Type
> As a user, I want to add a new battery brand-type-chemistry combination so I can track my inventory.

**Acceptance Criteria:**
- Can select from predefined form factors (AA, AAA, 18650, etc.) or add custom
- Can select from predefined chemistries (NiMH, Li-ion, etc.) or add custom
- Can enter brand name
- Can set initial quantity and status
- If the same brand-type-chemistry combination already exists, the quantity is added to the existing group (upsert behavior)

### US-02: View Inventory
> As a user, I want to see all my batteries at a glance so I know what's available.

**Acceptance Criteria:**
- Shows all brand-type-chemistry combinations
- Displays count per status (available/in-use/charging)
- Filterable by type, brand, or chemistry

### US-03: Assign to Device
> As a user, I want to assign batteries to a device so I can track where they are.

**Acceptance Criteria:**
- Select from existing devices or create new
- Specify quantity being assigned
- Automatically decrements "available" count

### US-04: Return from Device
> As a user, I want to mark batteries as returned from a device so they're back in inventory.

**Acceptance Criteria:**
- Can return all or partial quantity
- Choose destination: available or charging
- Updates device's battery assignment

### US-05: Manage Charging
> As a user, I want to track which batteries are charging so I know what will be available soon.

**Acceptance Criteria:**
- Move batteries to charging status
- Mark charging complete (moves to available)
- Optional: track charging start time

### US-06: Add Batteries to Existing Group
> As a user, I want to add more batteries to an existing group when I purchase more or find additional batteries.

**Acceptance Criteria:**
- When adding batteries with same brand-type-chemistry as existing group, quantity is added to that group
- User receives feedback indicating batteries were added to existing group vs new group created
- Works seamlessly whether user intentionally or accidentally selects existing combination

## 5. Data Model (Conceptual)

```
BatteryType (Form Factor)
├── id
├── name (AA, AAA, 18650, etc.)
└── isCustom

Chemistry (Battery Chemistry)
├── id
├── name (NiMH, Li-ion, LiFePO4, etc.)
└── isCustom

Brand
├── id
└── name

BatteryGroup (Brand + Type + Chemistry combination)
├── id
├── brandId
├── typeId
├── chemistryId
├── availableCount
├── chargingCount
└── notes

Device
├── id
├── name
└── description

DeviceBattery (Junction)
├── deviceId
├── batteryGroupId
├── quantity
└── assignedDate
```

## 6. UI/UX Requirements

### 6.1 Design Principles
- Clean, minimal interface
- Mobile-responsive (batteries often managed on-the-go)
- Quick actions accessible with minimal clicks
- Visual status indicators (color-coded)

### 6.2 Key Screens

1. **Dashboard** - Overview of all batteries, quick stats
2. **Battery List** - Detailed view with filtering
3. **Device List** - All devices and their battery assignments
4. **Add/Edit Battery** - Form for battery management
5. **Add/Edit Device** - Form for device management

### 6.3 Visual Indicators
- Green: Available
- Blue: In Use
- Orange/Yellow: Charging

## 7. Non-Functional Requirements

- **Performance**: Page load < 2s
- **Data Persistence**: All data persisted locally or in database
- **Offline Support**: Nice-to-have for future
- **Browser Support**: Modern browsers (Chrome, Firefox, Safari, Edge)

## 8. Out of Scope (v1)

- Individual battery serial number tracking
- Battery health/cycle tracking
- Multi-user support
- Barcode/QR scanning
- Push notifications
- Battery purchase history