From 38e08a0c8827de9739595c80f94ac6afc3da99a6 Mon Sep 17 00:00:00 2001 From: Igor Zamiatin Date: Sun, 28 Sep 2025 11:19:59 +0300 Subject: [PATCH] Add expense tracker Claude commands and documentation - Add .claude/ directory with commands for expense tracking - Add comprehensive documentation in docs/ - Example implementation of AI-powered expense management system --- .claude/commands/document-feature.md | 466 +++++++++++++++++++++++++ docs/technical/expense-management.md | 232 ++++++++++++ docs/user-guides/expense-management.md | 221 ++++++++++++ 3 files changed, 919 insertions(+) create mode 100644 .claude/commands/document-feature.md create mode 100644 docs/technical/expense-management.md create mode 100644 docs/user-guides/expense-management.md diff --git a/.claude/commands/document-feature.md b/.claude/commands/document-feature.md new file mode 100644 index 0000000..daeded7 --- /dev/null +++ b/.claude/commands/document-feature.md @@ -0,0 +1,466 @@ +# Document Feature Command + +Automatically generates comprehensive technical and user documentation for new features in the TaskFlow/ExpenseTracker application. + +## Usage +``` +/document-feature [feature-name] +``` + +## Parameters +- `feature-name`: The name of the feature to document (e.g., "export-system", "user-profile", "analytics-dashboard") + +## What This Command Does + +This command analyzes your codebase and generates two types of documentation: + +1. **Technical Documentation** (`docs/technical/[feature-name].md`) - For developers +2. **User Documentation** (`docs/user-guides/[feature-name].md`) - For end users + +## Command Implementation + +```typescript +// This command will: +// 1. Analyze the specified feature's code files +// 2. Generate technical documentation for developers +// 3. Create user-friendly guides with screenshot placeholders +// 4. Establish cross-references between both doc types + +import { analyzeFeatureFiles, generateTechnicalDocs, generateUserGuide } from '../utils/documentation'; + +async function documentFeature(featureName: string) { + console.log(`📝 Generating documentation for feature: ${featureName}`); + + // Step 1: Create documentation directories + await ensureDirectoriesExist(); + + // Step 2: Analyze codebase for feature-related files + const featureAnalysis = await analyzeFeatureFiles(featureName); + + // Step 3: Generate technical documentation + const techDoc = await generateTechnicalDocs(featureName, featureAnalysis); + + // Step 4: Generate user documentation + const userDoc = await generateUserGuide(featureName, featureAnalysis); + + // Step 5: Save documentation files + await saveDocs(featureName, techDoc, userDoc); + + console.log(`✅ Documentation generated successfully!`); + console.log(`📂 Technical docs: docs/technical/${featureName}.md`); + console.log(`👤 User guide: docs/user-guides/${featureName}.md`); +} + +async function ensureDirectoriesExist() { + // Create documentation directory structure + await createDirectories([ + 'docs', + 'docs/technical', + 'docs/user-guides', + 'docs/screenshots', + 'docs/api-reference' + ]); +} + +async function analyzeFeatureFiles(featureName: string) { + const patterns = [ + `src/components/**/*${featureName}*`, + `src/components/${featureName}/**/*`, + `src/app/**/*${featureName}*`, + `src/hooks/*${featureName}*`, + `src/utils/*${featureName}*`, + `src/types/*${featureName}*`, + `src/lib/*${featureName}*` + ]; + + const files = await findMatchingFiles(patterns); + const analysis = { + components: [], + hooks: [], + utilities: [], + types: [], + apiRoutes: [], + pages: [], + dependencies: [] + }; + + for (const file of files) { + const content = await readFile(file); + const fileAnalysis = await analyzeFileContent(content, file); + + // Categorize files and extract key information + if (file.includes('/components/')) { + analysis.components.push(fileAnalysis); + } else if (file.includes('/hooks/')) { + analysis.hooks.push(fileAnalysis); + } else if (file.includes('/utils/')) { + analysis.utilities.push(fileAnalysis); + } else if (file.includes('/types/')) { + analysis.types.push(fileAnalysis); + } else if (file.includes('/api/')) { + analysis.apiRoutes.push(fileAnalysis); + } else if (file.includes('/app/')) { + analysis.pages.push(fileAnalysis); + } + } + + return analysis; +} + +async function generateTechnicalDocs(featureName: string, analysis: any) { + return `# ${toTitleCase(featureName)} - Technical Documentation + +> **Feature**: ${featureName} +> **Generated**: ${new Date().toISOString().split('T')[0]} +> **Version**: 1.0.0 + +## Overview + +${generateFeatureOverview(analysis)} + +## Architecture + +### Components +${generateComponentDocs(analysis.components)} + +### Hooks +${generateHooksDocs(analysis.hooks)} + +### Utilities +${generateUtilityDocs(analysis.utilities)} + +### Types & Interfaces +${generateTypesDocs(analysis.types)} + +### API Endpoints +${generateApiDocs(analysis.apiRoutes)} + +## File Structure +\`\`\` +${generateFileStructure(analysis)} +\`\`\` + +## Dependencies +${generateDependencyDocs(analysis.dependencies)} + +## Implementation Details + +### Key Design Decisions +${generateDesignDecisions(analysis)} + +### Performance Considerations +${generatePerformanceNotes(analysis)} + +### Security Considerations +${generateSecurityNotes(analysis)} + +## Testing Strategy + +### Unit Tests +- [ ] Component rendering tests +- [ ] Hook behavior tests +- [ ] Utility function tests +- [ ] Type validation tests + +### Integration Tests +- [ ] API endpoint tests +- [ ] Component integration tests +- [ ] Data flow tests + +### E2E Tests +- [ ] User workflow tests +- [ ] Cross-browser compatibility +- [ ] Accessibility tests + +## Deployment Notes + +### Build Requirements +${generateBuildRequirements(analysis)} + +### Environment Variables +${generateEnvVarsDocs(analysis)} + +## Maintenance + +### Known Issues +- [ ] Document any known issues here + +### Future Enhancements +- [ ] Document planned improvements here + +### Troubleshooting +${generateTroubleshootingGuide(analysis)} + +## Related Documentation +- [User Guide](../user-guides/${featureName}.md) +- [API Reference](../api-reference/${featureName}.md) + +--- +*Generated by Claude Code documentation system* +`; +} + +async function generateUserGuide(featureName: string, analysis: any) { + return `# ${toTitleCase(featureName)} - User Guide + +> **Last Updated**: ${new Date().toISOString().split('T')[0]} +> **Difficulty**: Beginner +> **Estimated Time**: 5-10 minutes + +## What is ${toTitleCase(featureName)}? + +${generateUserFriendlyOverview(analysis)} + +## Getting Started + +### Prerequisites +- Ensure you have access to the application +- No special permissions required +- Works on all modern browsers + +### Quick Start +![Feature Overview](../screenshots/${featureName}-overview.png) +*Screenshot: ${toTitleCase(featureName)} main interface* + +1. **Access the feature** + - Navigate to [specific location] + - Click on "${toTitleCase(featureName)}" in the main menu + +2. **First-time setup** (if applicable) + - Follow the setup wizard + - Configure your preferences + +## Step-by-Step Guide + +### Basic Usage + +#### Step 1: [Primary Action] +![Step 1](../screenshots/${featureName}-step1.png) +*Screenshot: [Description of what user sees]* + +1. Click the "[Button Name]" button +2. Fill in the required information: + - **Field 1**: [Description and example] + - **Field 2**: [Description and example] +3. Click "Save" to continue + +#### Step 2: [Secondary Action] +![Step 2](../screenshots/${featureName}-step2.png) +*Screenshot: [Description of what user sees]* + +1. Review your information +2. Make any necessary changes +3. Confirm your settings + +### Advanced Features + +#### Feature A: [Advanced Feature Name] +![Advanced Feature A](../screenshots/${featureName}-advanced-a.png) +*Screenshot: Advanced feature interface* + +**When to use**: [Explain when this feature is useful] + +**How to use**: +1. [Step 1] +2. [Step 2] +3. [Step 3] + +**Tips**: +- 💡 [Helpful tip 1] +- ⚡ [Performance tip] +- ⚠️ [Important warning] + +## Common Use Cases + +### Use Case 1: [Scenario Name] +**Scenario**: [Describe common user scenario] + +**Solution**: +1. [Step 1] +2. [Step 2] +3. [Result] + +### Use Case 2: [Scenario Name] +**Scenario**: [Describe another scenario] + +**Solution**: +1. [Step 1] +2. [Step 2] +3. [Result] + +## Troubleshooting + +### Common Issues + +#### Issue: [Common Problem] +**Symptoms**: [What the user sees] +**Solution**: +1. [Solution step 1] +2. [Solution step 2] +3. [If still not working, try this] + +#### Issue: [Another Common Problem] +**Symptoms**: [What the user sees] +**Solution**: +1. [Solution step 1] +2. [Alternative approach] + +### Getting Help +- Check the [Technical Documentation](../technical/${featureName}.md) for detailed information +- Contact support at [support email/link] +- Join our community forum at [forum link] + +## Tips & Best Practices + +### Do's ✅ +- [Best practice 1] +- [Best practice 2] +- [Best practice 3] + +### Don'ts ❌ +- [Common mistake to avoid 1] +- [Common mistake to avoid 2] +- [Common mistake to avoid 3] + +## Keyboard Shortcuts + +| Action | Windows/Linux | Mac | +|--------|---------------|-----| +| [Action 1] | \`Ctrl+Key\` | \`Cmd+Key\` | +| [Action 2] | \`Ctrl+Shift+Key\` | \`Cmd+Shift+Key\` | + +## FAQ + +### Q: [Common Question 1] +**A**: [Clear, concise answer] + +### Q: [Common Question 2] +**A**: [Clear, concise answer with example if needed] + +### Q: [Common Question 3] +**A**: [Clear, concise answer] + +## What's Next? + +After mastering this feature, you might want to explore: +- [Related Feature 1](./related-feature-1.md) +- [Related Feature 2](./related-feature-2.md) +- [Advanced Guide](./advanced-${featureName}.md) + +--- + +## Screenshot Checklist +*For documentation maintainers* + +- [ ] \`${featureName}-overview.png\` - Main feature interface +- [ ] \`${featureName}-step1.png\` - First step screenshot +- [ ] \`${featureName}-step2.png\` - Second step screenshot +- [ ] \`${featureName}-advanced-a.png\` - Advanced features +- [ ] \`${featureName}-settings.png\` - Settings/configuration +- [ ] \`${featureName}-mobile.png\` - Mobile view (if applicable) + +*Generated by Claude Code documentation system* +`; +} + +async function saveDocs(featureName: string, techDoc: string, userDoc: string) { + const techPath = \`docs/technical/\${featureName}.md\`; + const userPath = \`docs/user-guides/\${featureName}.md\`; + + await writeFile(techPath, techDoc); + await writeFile(userPath, userDoc); + + // Also create API reference if API routes were found + // await generateApiReference(featureName, analysis); +} + +// Helper functions would be implemented here +function toTitleCase(str: string): string { + return str.split('-').map(word => + word.charAt(0).toUpperCase() + word.slice(1) + ).join(' '); +} + +function generateFeatureOverview(analysis: any): string { + // Analyze the code to generate an intelligent overview + return \`This feature provides [functionality] through [number] components, [number] hooks, and [number] utilities.\`; +} + +// Additional helper functions for generating specific documentation sections... +``` + +## Example Usage + +```bash +# Document the export system feature +/document-feature export-system + +# Document user profile functionality +/document-feature user-profile + +# Document analytics dashboard +/document-feature analytics-dashboard +``` + +## Generated File Structure + +After running this command, you'll have: + +``` +docs/ +├── technical/ +│ └── [feature-name].md # Technical documentation +├── user-guides/ +│ └── [feature-name].md # User-friendly guide +├── screenshots/ +│ ├── [feature-name]-overview.png # Screenshot placeholders +│ ├── [feature-name]-step1.png +│ └── [feature-name]-step2.png +└── api-reference/ + └── [feature-name].md # API documentation (if applicable) +``` + +## Features + +### Technical Documentation Includes: +- ✅ Architecture overview with component relationships +- ✅ File structure and organization +- ✅ API endpoints and data flow +- ✅ TypeScript interfaces and types +- ✅ Dependencies and build requirements +- ✅ Testing strategy and checklist +- ✅ Performance and security considerations +- ✅ Deployment and maintenance notes + +### User Documentation Includes: +- ✅ Simple, jargon-free explanations +- ✅ Screenshot placeholders with descriptive captions +- ✅ Step-by-step instructions with numbered lists +- ✅ Common use cases and scenarios +- ✅ Troubleshooting section with solutions +- ✅ Tips, best practices, and keyboard shortcuts +- ✅ FAQ section with common questions +- ✅ Cross-references to related features + +### Smart Analysis: +- 🔍 Automatically finds feature-related files +- 🧠 Analyzes code structure and dependencies +- 📊 Generates intelligent overviews based on code +- 🔗 Creates proper cross-references between docs +- 📸 Provides screenshot checklists for maintainers + +## Customization + +The command follows your project's established patterns: +- Uses existing component structure from `src/components/` +- Follows TypeScript conventions from your codebase +- Matches the style of your current README.md +- Integrates with your Next.js application architecture + +## Integration + +This command works seamlessly with your existing workflow: +- Respects your git branching strategy (`feature-*`) +- Follows SOLID design principles +- Uses your established file organization patterns +- Maintains consistency with current documentation style \ No newline at end of file diff --git a/docs/technical/expense-management.md b/docs/technical/expense-management.md new file mode 100644 index 0000000..7e3b4de --- /dev/null +++ b/docs/technical/expense-management.md @@ -0,0 +1,232 @@ +# Expense Management - Technical Documentation + +> **Feature**: expense-management +> **Generated**: 2025-09-28 +> **Version**: 1.0.0 + +## Overview + +The Expense Management feature provides comprehensive CRUD functionality for expense tracking through 4 main components, 1 custom hook, and 3 utility functions. This feature handles the core business logic for creating, reading, updating, and deleting expense records with form validation and local storage persistence. + +## Architecture + +### Components + +#### ExpenseForm (`src/components/forms/ExpenseForm.tsx`) +- **Purpose**: Handles expense creation and editing with form validation +- **Props**: + - `expense?: Expense` - Optional expense for editing mode + - `onSave: (expense: Expense) => void` - Callback for saving expense + - `onCancel: () => void` - Callback for canceling operation +- **State Management**: Local form state with validation +- **Dependencies**: date-fns for date handling, lucide-react for icons + +#### ExpenseList (`src/components/ExpenseList.tsx`) +- **Purpose**: Displays paginated list of expenses with sorting and actions +- **Props**: + - `expenses: Expense[]` - Array of expenses to display + - `onEdit: (expense: Expense) => void` - Edit callback + - `onDelete: (id: string) => void` - Delete callback +- **Features**: Sorting by date/amount, edit/delete actions, responsive design + +#### ExpenseFilters (`src/components/ExpenseFilters.tsx`) +- **Purpose**: Provides filtering and search functionality +- **Props**: + - `onFilter: (filters: FilterOptions) => void` - Filter callback + - `categories: ExpenseCategory[]` - Available categories +- **Filters**: Date range, category, amount range, text search + +#### SummaryCard (`src/components/SummaryCard.tsx`) +- **Purpose**: Displays expense summary statistics +- **Props**: + - `title: string` - Card title + - `value: string | number` - Primary value + - `icon: LucideIcon` - Display icon + - `trend?: number` - Optional trend indicator + +### Hooks + +#### useExpenses (`src/hooks/useExpenses.ts`) +- **Purpose**: Centralized expense state management +- **Returns**: + - `expenses: Expense[]` - Current expense list + - `addExpense: (expense: Omit) => void` + - `updateExpense: (id: string, expense: Partial) => void` + - `deleteExpense: (id: string) => void` + - `getExpensesByCategory: () => CategorySummary[]` + - `getTotalExpenses: () => number` +- **Storage**: Uses localStorage for persistence +- **Validation**: Validates expense data before operations + +### Utilities + +#### Currency Formatting (`src/utils/currency.ts`) +- `formatCurrency(amount: number): string` - Formats numbers as USD currency +- Handles locale-specific formatting and edge cases + +#### Date Utilities (`src/utils/dateUtils.ts`) +- `formatDate(date: Date): string` - Consistent date formatting +- `isWithinDateRange(date: Date, start: Date, end: Date): boolean` +- `getMonthlyGrouping(expenses: Expense[]): MonthlyData[]` + +#### Export Utilities (`src/utils/exportUtils.ts`) +- `exportToCSV(expenses: Expense[]): void` - Exports expenses as CSV +- `generateExpenseReport(expenses: Expense[]): ReportData` +- Handles data transformation and file download + +### Types & Interfaces + +#### Core Types (`src/types/expense.ts`) +```typescript +export interface Expense { + id: string; + amount: number; + category: ExpenseCategory; + description: string; + date: Date; + createdAt: Date; + updatedAt: Date; +} + +export type ExpenseCategory = + | 'Food' + | 'Transportation' + | 'Entertainment' + | 'Shopping' + | 'Bills' + | 'Other'; + +export interface FilterOptions { + category?: ExpenseCategory; + dateRange?: { start: Date; end: Date }; + amountRange?: { min: number; max: number }; + searchText?: string; +} +``` + +### API Endpoints + +No backend API - uses localStorage for data persistence. Future enhancement would include: +- `GET /api/expenses` - Fetch expenses +- `POST /api/expenses` - Create expense +- `PUT /api/expenses/:id` - Update expense +- `DELETE /api/expenses/:id` - Delete expense + +## File Structure +``` +src/ +├── components/ +│ ├── forms/ +│ │ └── ExpenseForm.tsx +│ ├── ExpenseList.tsx +│ ├── ExpenseFilters.tsx +│ └── SummaryCard.tsx +├── hooks/ +│ └── useExpenses.ts +├── types/ +│ └── expense.ts +├── utils/ +│ ├── currency.ts +│ ├── dateUtils.ts +│ └── exportUtils.ts +└── app/ + ├── add-expense/ + ├── expenses/ + └── analytics/ +``` + +## Dependencies +- **date-fns**: Date manipulation and formatting +- **lucide-react**: Icons for UI components +- **react**: Core React functionality +- **typescript**: Type safety and development experience + +## Implementation Details + +### Key Design Decisions +1. **Local Storage**: Chose localStorage over backend for simplicity and offline capability +2. **Custom Hook Pattern**: Centralized state management through useExpenses hook +3. **Component Composition**: Separated form, list, and filter concerns for reusability +4. **Type Safety**: Comprehensive TypeScript interfaces for all data structures + +### Performance Considerations +- Lazy loading for large expense lists +- Debounced search input to prevent excessive filtering +- Memoized calculations for summary statistics +- Efficient date range filtering using binary search approach + +### Security Considerations +- Input validation on all form fields +- XSS prevention through proper escaping +- No sensitive data exposure in localStorage +- Form validation prevents malicious input + +## Testing Strategy + +### Unit Tests +- [x] ExpenseForm validation logic +- [x] useExpenses hook operations +- [x] Currency formatting utilities +- [ ] Date utility functions +- [ ] Export functionality + +### Integration Tests +- [ ] Form submission flow +- [ ] Filter and search integration +- [ ] List rendering with various data sets +- [ ] Local storage persistence + +### E2E Tests +- [ ] Complete expense creation workflow +- [ ] Edit and delete operations +- [ ] Export functionality +- [ ] Mobile responsive behavior + +## Deployment Notes + +### Build Requirements +- Node.js 18+ +- Next.js 15.5.4+ +- TypeScript 5+ +- No external database required + +### Environment Variables +No environment variables required for basic functionality. +For future enhancements: +- `DATABASE_URL` - Database connection string +- `API_BASE_URL` - Backend API URL + +## Maintenance + +### Known Issues +- [ ] Large datasets (1000+ expenses) may cause performance issues +- [ ] Browser storage limits not handled gracefully +- [ ] No data backup/restore functionality + +### Future Enhancements +- [ ] Backend API integration +- [ ] Real-time sync across devices +- [ ] Advanced reporting features +- [ ] Receipt image attachments +- [ ] Budget tracking integration + +### Troubleshooting + +#### Issue: Expenses not persisting between sessions +**Cause**: Browser storage disabled or full +**Solution**: Check browser storage settings, clear unnecessary data + +#### Issue: Form validation not working +**Cause**: JavaScript disabled or component state issues +**Solution**: Verify form component props and validation rules + +#### Issue: Export feature not working +**Cause**: Browser download restrictions +**Solution**: Check browser download settings and permissions + +## Related Documentation +- [User Guide](../user-guides/expense-management.md) +- [API Reference](../api-reference/expense-management.md) + +--- +*Generated by Claude Code documentation system* \ No newline at end of file diff --git a/docs/user-guides/expense-management.md b/docs/user-guides/expense-management.md new file mode 100644 index 0000000..71f0b34 --- /dev/null +++ b/docs/user-guides/expense-management.md @@ -0,0 +1,221 @@ +# Expense Management - User Guide + +> **Last Updated**: 2025-09-28 +> **Difficulty**: Beginner +> **Estimated Time**: 5-10 minutes + +## What is Expense Management? + +The Expense Management feature is the heart of your personal finance tracker. It allows you to record, organize, and manage all your daily expenses in one place. Whether you're tracking a morning coffee or a monthly rent payment, this feature makes it simple to keep tabs on your spending habits. + +## Getting Started + +### Prerequisites +- Access to the ExpenseTracker application +- A modern web browser (Chrome, Firefox, Safari, Edge) +- No special permissions required + +### Quick Start +![Expense Management Overview](../screenshots/expense-management-overview.png) +*Screenshot: Main expense management interface showing your expense list and summary* + +1. **Access the feature** + - Navigate to the application homepage + - The expense list is visible right on the dashboard + +2. **First-time setup** + - No setup required - start adding expenses immediately! + - Your data is automatically saved in your browser + +## Step-by-Step Guide + +### Basic Usage + +#### Step 1: Adding Your First Expense +![Add Expense Form](../screenshots/expense-management-step1.png) +*Screenshot: The expense creation form with all fields visible* + +1. Click the "Add Expense" button (green plus icon) +2. Fill in the expense details: + - **Amount**: Enter the cost (e.g., 15.50) + - **Category**: Choose from dropdown (Food, Transportation, Entertainment, Shopping, Bills, Other) + - **Description**: Add details (e.g., "Lunch at Tony's Deli") + - **Date**: Select when the expense occurred (defaults to today) +3. Click "Add Expense" to save + +**Example**: Coffee purchase +- Amount: $4.75 +- Category: Food +- Description: "Morning coffee at Starbucks" +- Date: Today's date + +#### Step 2: Viewing Your Expenses +![Expense List View](../screenshots/expense-management-step2.png) +*Screenshot: List of expenses showing date, description, category, and amount* + +1. Your expenses appear immediately in the main list +2. Most recent expenses are shown first +3. Each expense shows: + - Date and description + - Category with color coding + - Amount in your currency + - Edit and delete buttons + +### Advanced Features + +#### Feature A: Filtering and Searching +![Advanced Filtering](../screenshots/expense-management-advanced-a.png) +*Screenshot: Filter panel showing category, date range, and search options* + +**When to use**: When you have many expenses and need to find specific ones quickly + +**How to use**: +1. Use the search box to find expenses by description +2. Filter by category using the dropdown menu +3. Set date ranges to view expenses from specific periods +4. Combine filters for precise results + +**Tips**: +- 💡 Search works on descriptions - be descriptive when adding expenses +- ⚡ Use category filters to analyze spending patterns +- ⚠️ Clear filters to see all expenses again + +#### Feature B: Editing Expenses +**When to use**: When you need to correct a mistake or update details + +**How to use**: +1. Find the expense in your list +2. Click the edit button (pencil icon) +3. Make your changes in the form +4. Click "Update Expense" to save + +#### Feature C: Deleting Expenses +**When to use**: When you accidentally added a duplicate or incorrect expense + +**How to use**: +1. Find the expense you want to remove +2. Click the delete button (trash icon) +3. Confirm deletion in the popup +4. The expense is permanently removed + +## Common Use Cases + +### Use Case 1: Weekly Expense Review +**Scenario**: You want to see what you spent this week + +**Solution**: +1. Use the date filter to select "Last 7 days" +2. Review the list of expenses +3. Check the total at the bottom +4. Export to CSV if you need to share with someone + +### Use Case 2: Category Budget Tracking +**Scenario**: You want to see how much you're spending on food + +**Solution**: +1. Filter by "Food" category +2. Set date range to "This month" +3. View the filtered total +4. Compare against your food budget + +### Use Case 3: Finding a Specific Purchase +**Scenario**: You need to find that restaurant expense from last month + +**Solution**: +1. Use the search box and type the restaurant name +2. Or filter by "Food" category and browse by date +3. Click edit to view full details + +## Troubleshooting + +### Common Issues + +#### Issue: My expenses disappeared +**Symptoms**: The expense list is empty or missing recent entries +**Solution**: +1. Check if any filters are active - clear all filters +2. Refresh the browser page +3. Make sure you're using the same browser where you added expenses +4. Check if browser storage was cleared + +#### Issue: Can't add new expense +**Symptoms**: Add expense button doesn't work or form won't submit +**Solution**: +1. Make sure all required fields are filled +2. Check that the amount is a valid number +3. Refresh the page and try again +4. Make sure JavaScript is enabled in your browser + +#### Issue: Export isn't working +**Symptoms**: CSV download doesn't start when clicking export +**Solution**: +1. Check your browser's download settings +2. Disable popup blockers for this site +3. Try right-clicking the export button and select "Save link as..." + +### Getting Help +- Check the [Technical Documentation](../technical/expense-management.md) for detailed information +- Clear your browser cache if you experience persistent issues +- Use a different browser to test if issues are browser-specific + +## Tips & Best Practices + +### Do's ✅ +- Be descriptive with expense descriptions for easy searching +- Add expenses daily to avoid forgetting them +- Use appropriate categories for better analysis +- Review your expenses weekly to stay on track +- Export data regularly as a backup + +### Don'ts ❌ +- Don't forget to select the correct date for past expenses +- Don't use vague descriptions like "stuff" or "things" +- Don't rely solely on browser storage - export important data +- Don't add duplicate expenses (check first) + +## Keyboard Shortcuts + +| Action | Windows/Linux | Mac | +|--------|---------------|-----| +| Add New Expense | `Ctrl+N` | `Cmd+N` | +| Search Expenses | `Ctrl+F` | `Cmd+F` | +| Clear Filters | `Ctrl+R` | `Cmd+R` | +| Export Data | `Ctrl+E` | `Cmd+E` | + +## FAQ + +### Q: Where is my expense data stored? +**A**: Your expenses are stored locally in your browser's storage. This means your data stays private but is only available on the device and browser where you entered it. + +### Q: Can I access my expenses from multiple devices? +**A**: Currently, no. Expenses are stored locally per browser. We recommend exporting your data regularly and importing it on other devices when that feature becomes available. + +### Q: Is there a limit to how many expenses I can add? +**A**: Browser storage limits vary, but you can typically store thousands of expenses. If you're approaching limits, consider exporting older data and removing it from the active list. + +### Q: Can I import expenses from my bank or credit card? +**A**: Currently, manual entry only. Future versions may include import capabilities from CSV files or financial institutions. + +### Q: What happens if I accidentally delete an expense? +**A**: Deleted expenses cannot be recovered. Be careful when deleting, and consider exporting your data regularly as a backup. + +## What's Next? + +After mastering expense management, you might want to explore: +- [Analytics Dashboard](./analytics-dashboard.md) - Visualize your spending patterns +- [Export System](./export-system.md) - Advanced data export options +- [Budget Tracking](./budget-tracking.md) - Set and monitor spending limits + +--- + +## Screenshot Checklist +*For documentation maintainers* + +- [ ] `expense-management-overview.png` - Main expense interface +- [ ] `expense-management-step1.png` - Add expense form +- [ ] `expense-management-step2.png` - Expense list view +- [ ] `expense-management-advanced-a.png` - Filter and search features +- [ ] `expense-management-settings.png` - Category settings +- [ ] `expense-management-mobile.png` - Mobile responsive view + +*Generated by Claude Code documentation system* \ No newline at end of file