Penny 💰

A modern React-based personal finance application for categorizing and visualizing CSV transaction data with beautiful charts and expense tracking.

✨ Features

📊 Expense Visualization

• Interactive bar charts showing spending by category
• Faded color palette optimized for both light and dark modes
• Toggle categories to focus on specific spending areas
• Data filtering and visualization

🔧 Smart Categorization

• Intelligent rule-based transaction categorization
• Support for regex and simple text matching patterns
• Batch categorization for efficient transaction processing
• Pre-configured rules for common NYC spending patterns

🌙 Dark Mode Support

• Full dark mode implementation with proper contrast ratios
• Seamless theme switching with persistent user preference
• Optimized colors for accessibility in both light and dark themes

📱 Mobile-First Design

• Responsive design that works beautifully on all devices
• Touch-friendly interface optimized for mobile usage
• Progressive enhancement for desktop features

💾 Local-First Storage

• All data stored locally in browser localStorage
• No server required - complete privacy for your financial data
• Import/export functionality for data portability
• Supports 20,000+ transactions with efficient storage

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm
• Modern web browser with ES2022 support

Installation

1. Clone the repository

   git clone <repository-url>
   cd penny

2. Install dependencies

   npm install

3. Start the development server

   npm run dev
   # or
   npm start

4. Open your browser

   http://localhost:3000
   

Sample Data

Try the app with sample data:

• Import data/nyc_demo.csv for NYC-based transaction examples
• The app includes smart categorization rules for common merchants

🏗️ Tech Stack

Core Framework

• React 19 with TypeScript for type-safe development
• TanStack Router for file-based routing with type safety
• TanStack Query for efficient state management
• Vite for fast development and optimized builds

UI & Styling

• Tailwind CSS v4 for utility-first styling
• Shadcn/ui components for consistent design system
• Recharts for interactive data visualizations
• Lucide Icons for consistent iconography

Data Processing

• PapaParse for robust CSV parsing and processing
• Custom algorithms for intelligent transaction categorization
• Efficient filtering and search capabilities

Development Tools

• Vitest for fast unit and integration testing
• React Testing Library for component testing
• Biome for lightning-fast linting and formatting
• TypeScript for compile-time error catching

Key Features Implementation

CSV Processing

• Delimiter auto-detection for various CSV formats
• Column normalization to handle different bank export formats
• Data validation and error handling for malformed data

Rule Engine

• Regex patterns for advanced merchant matching
• Simple text matching for basic categorization
• Rule priority system with first-match wins
• Bulk operations for efficient rule management

Dark Mode

• CSS custom properties for theme-aware colors
• System preference detection with manual override
• Persistent user preference in localStorage
• Optimized contrast ratios for accessibility

🧪 Testing

The app includes comprehensive test coverage:

• Component tests for all major UI components
• Hook tests for custom React hooks
• Utility tests for data processing functions
• Integration tests for complete user workflows

Run tests with detailed coverage:

npm run test -- --coverage

📈 Performance

Optimization Features

• Virtual scrolling for large transaction lists (1000+ items)
• Memoized calculations for expensive operations
• Efficient re-renders with React.memo and useMemo
• Lazy loading for route-based code splitting

Storage Capacity

• Current limit: ~20,000-30,000 transactions in localStorage
• Performance degradation: Noticeable around 5,000-10,000 transactions
• Optimization opportunities: Data compression, pagination, IndexedDB migration

🗺️ Roadmap

• Expense Drilldown: Click categories in charts to view filtered transaction details
• Custom Filtering: Advanced filtering options for dates, amounts, and categories
• IndexedDB Migration: Replace localStorage with IndexedDB for better scalability and performance

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: npm run test
5. Check code quality: npm run check
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

📝 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Shadcn/ui for the beautiful component system
• TanStack for the excellent React ecosystem tools
• Recharts for powerful yet simple data visualization
• The React community for continuous innovation and support

---

Built with ❤️ using modern React and TypeScript