Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mooshieblob1/project-2-cst-182

A simple command-line personal finance tracker in Python for managing income/expenses with CSV data persistence, financial summaries, and transaction history
https://github.com/mooshieblob1/project-2-cst-182

Last synced: 10 months ago
JSON representation

A simple command-line personal finance tracker in Python for managing income/expenses with CSV data persistence, financial summaries, and transaction history

Awesome Lists containing this project

README 

          
# Enhanced Finance Tracker



A modern, feature-rich personal finance tracking web application built with SvelteKit 5.0, TypeScript, and Tailwind CSS. This comprehensive finance tracker provides advanced analytics, data visualization, and an enhanced user experience for managing your personal finances.



**🌐 Application Type**: Modern Web Application (SvelteKit PWA)

**🚀 Ready to use**: Build with `pnpm install && pnpm dev`

**📱 Responsive**: Works on desktop, tablet, and mobile devices



## ✨ Comprehensive Feature Set



### 🏠 Core Functionality



- **Transaction Management**: Add, view, edit, and categorize income and expense transactions

- **Real-time Balance Tracking**: Automatic calculation of account balance with income/expense totals

- **CSV Data Handling**: Import existing CSV data and export transactions for backup

- **Local Data Persistence**: Automatic saving to browser localStorage with session persistence

- **Data Import/Export**: Upload CSV files and download your transaction data



### � Advanced Analytics & Insights



- **Interactive Charts**: Donut charts for expense categories, time-series for balance trends

- **Spending Insights**: Average transaction analysis, largest expense tracking, category breakdowns

- **Date Filtering**: Flexible filtering by week, month, quarter, year, or custom date ranges

- **Monthly Trends**: Visual tracking of spending patterns over time

- **Category Analysis**: Detailed percentage breakdowns of spending by category

- **Real-time Calculations**: All statistics update instantly as transactions are added/removed



### 🔧 Enhanced Transaction Management



- **Advanced Search**: Multi-criteria filtering by description, category, amount, and date

- **Smart Sorting**: Sort by date, amount, category, or description (ascending/descending)

- **Bulk Operations**: Export filtered data, bulk deletion with confirmation dialogs

- **Real-time Updates**: All views update instantly when data changes

- **Collapsible Filters**: Advanced filtering options with clear all functionality

- **Amount Range Filtering**: Filter transactions by minimum and maximum amounts



### 🎨 User Experience & Design



- **Modern Dark Theme**: Professional dark mode interface with optimal contrast and accessibility

- **Responsive Design**: Mobile-first design that adapts to all screen sizes

- **Accessible Interface**: Screen reader support, keyboard navigation, proper ARIA labels

- **Fast Performance**: Client-side application with instant interactions and zero server dependency

- **Touch-Friendly**: Large touch targets optimized for mobile devices

- **Loading States**: Proper feedback for user actions and data operations



## 🛠️ Technology Stack



- **Framework**: SvelteKit 5.0 with Svelte 5 runes ($state, $derived)

- **Language**: TypeScript for full type safety

- **Styling**: Tailwind CSS 4.0 for modern utility-first styling

- **Build Tool**: Vite for fast development and optimized builds

- **Deployment**: Cloudflare Pages adapter included



## 🚀 Quick Start



### Prerequisites



- **Node.js** (version 18 or higher)

- **pnpm** (recommended package manager)



### Getting Started



1. **Clone the repository**:



   ```bash

   git clone https://github.com/Mooshieblob1/Project-2-CST-182.git

   cd Project-2-CST-182

   ```



2. **Install dependencies**:



   ```bash

   pnpm install

   ```



3. **Start development server**:



   ```bash

   pnpm dev

   ```



4. **Open your browser** and navigate to `http://localhost:5173`



### Build for Production



```bash

# Build the application

pnpm build



# Preview the built application

pnpm preview

```



## �️ Application Navigation & Features



### Main Navigation Tabs



1. **Add Transaction** - Form interface to add new income/expense entries with category and date selection

2. **Summary** - Basic financial overview with time-based filtering and balance calculations

3. **Analytics** - Advanced insights with interactive charts, spending analysis, and trend visualizations

4. **Transactions** - Simple transaction listing view with basic sorting and viewing options

5. **Manage** - Advanced transaction management with comprehensive filtering, search, and bulk operations

6. **Data** - Complete data management including CSV import/export, data reset, and bulk operations



### Analytics Features (Enhanced Summary)



- **Date Filtering**: Filter by All Time, This Week, This Month, This Quarter, This Year, or Custom Date Range

- **Spending Insights**:

  - Average transaction amount calculation

  - Largest expense tracking and identification

  - Top spending category identification

  - Detailed percentage breakdown of spending by category

- **Visual Analytics**: Donut charts for category breakdowns, time-series charts for balance trends

- **Monthly Trends**: Visual display of month-over-month income and expense patterns

- **Real-time Updates**: All calculations and charts update instantly as transactions are added/removed



### Enhanced Transaction Management (Manage Tab)



- **Advanced Filtering Options**:

  - Search by description or category with real-time results

  - Filter by transaction type (income/expense/both)

  - Category-specific filtering with dropdown selection

  - Amount range filtering (minimum and maximum values)

  - Date range filtering (from/to dates with date pickers)

- **Enhanced Sorting**: Sort by date, amount, category, or description (ascending/descending)

- **Bulk Operations**:

  - Export filtered data to CSV with automatic filename generation

  - Clear all transactions with confirmation dialog

  - Real-time filtered summary displaying income, expenses, and balance for current filters

- **User Experience Improvements**:

  - Collapsible advanced filters section

  - Clear all filters button for easy reset

  - Real-time filter count display

  - Responsive design optimized for mobile and desktop



### Data Management Features



- **Automatic CSV Loading**: Loads existing `transactions.csv` from static folder on first startup

- **Browser Storage**: Automatic persistence to localStorage for session management

- **CSV Export**: Download all transactions or filtered subsets with date-stamped filenames

- **Data Import**: Upload CSV files to import additional transaction data

- **Reset & Reload**: Force clean restart with fresh CSV data if needed

- **Data Overview**: Statistics display showing total transactions and current balance



## 🏗️ Technical Architecture & Project Structure



### Modern Technology Stack



- **SvelteKit 5.0**: Latest version with Svelte 5 runes ($state, $derived) for reactive state management

- **TypeScript**: Full type safety throughout the application with comprehensive interface definitions

- **Tailwind CSS 4.0**: Modern utility-first CSS framework with dark theme optimization

- **Vite**: Fast build tool for development and optimized production builds

- **Cloudflare Pages Adapter**: Pre-configured for edge deployment and static generation



### Project File Structure



```

Project/

├── src/

│   ├── routes/

│   │   ├── +layout.svelte      # Application layout with dark theme enforcement

│   │   └── +page.svelte        # Main application page with navigation and view switching

│   ├── lib/

│   │   ├── components/         # Modular Svelte components

│   │   │   ├── EnhancedSummary.svelte        # Analytics tab with charts and insights

│   │   │   ├── EnhancedTransactionList.svelte # Advanced transaction management

│   │   │   ├── Summary.svelte                # Basic financial overview

│   │   │   ├── TransactionForm.svelte        # Transaction entry form

│   │   │   └── TransactionList.svelte        # Simple transaction listing

│   │   ├── stores/            # Centralized state management

│   │   │   └── transactions.ts     # Transaction store with localStorage persistence

│   │   └── csvLoader.ts       # CSV parsing and data import utilities

│   ├── app.css               # Global styles and Tailwind configuration

│   └── app.html              # HTML template with meta tags and favicons

├── static/

│   ├── transactions.csv      # Sample transaction data for initial loading

│   └── favicon.svg          # Application icon

├── package.json             # Dependencies and build scripts

├── svelte.config.js         # SvelteKit configuration with Cloudflare adapter

├── tailwind.config.ts       # Tailwind CSS configuration with dark theme

├── tsconfig.json           # TypeScript configuration

└── vite.config.ts          # Vite build configuration

```



### State Management Architecture



- **Reactive Store**: Centralized transaction management using Svelte stores with automatic persistence

- **localStorage Integration**: Seamless saving/loading of transaction data across browser sessions

- **Real-time Updates**: All components reactively update when transaction data changes

- **Type Safety**: Complete TypeScript coverage with defined interfaces for all data structures



### Performance & Optimization Features



- **Lazy Loading**: Components and calculations load only when needed

- **Efficient Filtering**: Optimized derived state calculations for large datasets

- **Memory Management**: Proper cleanup of subscriptions and reactive statements

- **Client-side Processing**: No server dependency - fully functional offline web application



### Accessibility & UX Features



- **Screen Reader Support**: Comprehensive ARIA labels and semantic HTML structure

- **Keyboard Navigation**: Full keyboard accessibility for all interactive elements

- **High Contrast Design**: Optimized color scheme for visual accessibility in dark mode

- **Responsive Design**: Mobile-first approach with adaptive layouts for all screen sizes

- **Touch-Friendly Interface**: Large touch targets and gesture-friendly interactions



## 📖 Detailed Usage Guide



### Getting Started with Your Data



1. **First Time Setup**:

   - Visit `http://localhost:5173` in your browser

   - The app automatically loads sample transactions from `transactions.csv`

   - Your existing financial data is immediately available for analysis



2. **Sample Data Included**:

   - Gift from Brother: $100.00 (Income)

   - Salary: $2,100.00 (Income)

   - Food: $200.00 (Expense)

   - Luke's Clothes: $100.00 (Income)

   - Salary Dividends: $400.00 (Income)

   - **Total Balance: $3,700.00** (Income: $3,900.00, Expenses: $200.00)



### Adding New Transactions



1. Navigate to the **Add Transaction** tab

2. Select transaction type (Income/Expense) using the toggle buttons

3. Enter amount (accepts decimal values, automatically formatted)

4. Choose from predefined categories or enter custom category

5. Add detailed description for transaction tracking

6. Select date (defaults to current date, full date picker available)

7. Click "Add Transaction" to save (automatically updates all views)



### Exploring Analytics & Insights



1. Go to the **Analytics** tab for comprehensive financial analysis

2. **Date Filtering Options**:

   - All Time: Complete transaction history

   - This Week/Month/Quarter/Year: Predefined time periods

   - Custom Range: Select specific start and end dates

3. **Spending Insights Available**:

   - Average transaction amount across selected period

   - Largest single expense identification and amount

   - Top spending category with percentage of total expenses

   - Complete category breakdown with visual percentages

4. **Visual Analytics**:

   - Interactive donut chart for expense category distribution

   - Time-series chart showing balance trends over time

   - Monthly income vs expense comparison charts



### Advanced Transaction Management



1. Visit the **Manage** tab for comprehensive transaction control

2. **Search & Filter Options**:

   - **Text Search**: Search by description or category (real-time results)

   - **Type Filter**: Show income only, expenses only, or both

   - **Category Filter**: Dropdown selection of all available categories

   - **Amount Range**: Set minimum and maximum transaction amounts

   - **Date Range**: Select from and to dates with date picker interface

3. **Sorting & Organization**:

   - Sort by any column (date, amount, category, description)

   - Toggle ascending/descending order with visual indicators

   - Maintained sort order across filter changes

4. **Bulk Operations**:

   - Export filtered results to CSV with automatic date-stamped filename

   - Clear all transactions with confirmation dialog for safety

   - View real-time summary of filtered data (income, expenses, balance)



### Data Import/Export Operations



1. Access the **Data** tab for complete data management

2. **Import Options**:

   - **Load CSV Data**: Import your existing transaction CSV files

   - **File Upload**: Drag and drop or browse for additional CSV files

   - **Format Support**: Standard CSV format with headers (Date, Amount, Category, Description, Type)

3. **Export Features**:

   - **Full Export**: Download all transactions with "Export to CSV"

   - **Filtered Export**: Export only currently filtered/searched transactions

   - **Automatic Naming**: Files include current date and time in filename

4. **Data Management**:

   - **Reset & Reload**: Clear all data and reload fresh from CSV (useful for troubleshooting)

   - **Data Statistics**: View total transaction count and current balance

   - **Storage Info**: Monitor localStorage usage and data persistence status



## 🔧 Development & Build Process



### Available Build Scripts



```bash

# Development Commands

pnpm dev              # Start development server with hot reload

pnpm dev --open       # Start server and automatically open browser

pnpm dev --host       # Expose dev server to network (useful for mobile testing)



# Production Build Commands

pnpm build            # Build optimized production version

pnpm preview          # Preview production build locally



# Code Quality & Maintenance

pnpm check            # Run TypeScript type checking

pnpm check:watch      # Type checking in watch mode for continuous validation

pnpm format           # Format code using Prettier

pnpm lint             # Lint code using ESLint with Svelte-specific rules



# Package Management

pnpm install          # Install all dependencies

pnpm update           # Update dependencies to latest compatible versions

```



### Code Quality Standards



- **TypeScript**: Complete type safety across all components and utilities

- **ESLint**: Comprehensive linting with Svelte-specific rules and best practices

- **Prettier**: Automatic code formatting for consistent style

- **Svelte Check**: Component validation and advanced type checking for Svelte files



### Development Environment Setup



1. **Node.js Requirements**: Version 18 or higher (LTS recommended)

2. **Package Manager**: pnpm is strongly recommended for optimal performance

3. **Editor Setup**: VS Code with Svelte and TypeScript extensions recommended

4. **Browser Support**: Modern browsers (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)



## 🚀 Deployment Options



### Cloudflare Pages (Recommended)



The application is pre-configured for Cloudflare Pages deployment with optimal settings:



1. **Build Configuration**: `pnpm build` generates optimized static files

2. **Deploy Directory**: Upload the `build` directory to Cloudflare Pages

3. **Adapter Benefits**:

   - Server-side rendering where beneficial

   - Static generation for optimal performance

   - Edge deployment for global low latency

   - Automatic HTTPS and CDN distribution



**Deployment Steps**:



```bash

# Build for production

pnpm build



# Deploy build/ directory to Cloudflare Pages

# Or connect your Git repository for automatic deployments

```



### Alternative Hosting Platforms



The application works with any static hosting service:



- **Vercel**: Zero-config deployment with Git integration

- **Netlify**: Continuous deployment with form handling and serverless functions

- **GitHub Pages**: Free hosting for open source projects

- **AWS S3 + CloudFront**: Enterprise-grade hosting with global CDN

- **Firebase Hosting**: Google's static hosting with easy SSL and custom domains



**Universal Static Deployment**:



```bash

pnpm build

# Upload build/ directory to your preferred hosting service

```



## ✅ Issues Resolved & Stability



### Recent Fixes Applied



**Performance Optimizations**:



- ✅ Fixed infinite loops in reactive derivations that caused application freezing

- ✅ Resolved Svelte 5 compilation errors with proper $derived syntax usage

- ✅ Optimized state management to prevent circular dependencies

- ✅ Added proper async handling for CSV operations with timeout buffers



**User Interface Improvements**:



- ✅ Enforced consistent dark mode theming throughout the application

- ✅ Removed problematic theme toggle to prevent module errors

- ✅ Enhanced responsive design for optimal mobile device experience

- ✅ Improved accessibility with proper keyboard navigation and screen reader support



**Data Management Enhancements**:



- ✅ Automatic CSV loading on application startup when no localStorage data exists

- ✅ Improved error handling for file operations with informative user feedback

- ✅ Added Reset & Reload functionality for data troubleshooting

- ✅ Enhanced CSV import/export with better format validation



### Application Status: Fully Functional ✅



- **All Navigation Tabs**: Working without freezing or errors

- **CSV Data Integration**: Automatic loading and seamless import/export

- **Interactive Features**: All buttons, filters, and forms fully responsive

- **Build System**: Clean compilation with no TypeScript or Svelte errors

- **Cross-Platform**: Tested on desktop, tablet, and mobile devices



**If you experience any issues**:



1. Navigate to the **Data** tab

2. Click **"Reset & Reload"** to force a clean restart with fresh CSV data

3. Clear browser cache if persistent issues occur



## 🤝 Contributing & Future Enhancements



### Areas for Enhancement



**Advanced Features**:



- **Budget Planning**: Add budget setting, tracking, and alert systems

- **Recurring Transactions**: Support for automated recurring income/expenses

- **Multi-currency Support**: International currency handling with exchange rates

- **Advanced Reporting**: Detailed financial reports with PDF export

- **Goal Setting**: Financial goal tracking with progress visualization



**Data & Analytics**:



- **Additional Chart Types**: Bar charts, line graphs, pie charts for different data views

- **Trend Analysis**: Advanced statistical analysis and forecasting

- **Comparative Analytics**: Year-over-year, month-over-month comparison tools

- **Category Management**: Custom category creation, editing, and organization

- **Tag System**: Advanced tagging system for transaction organization



**Integration & Sync**:



- **Cloud Backup**: Integration with cloud storage providers

- **Multi-device Sync**: Synchronization across multiple devices

- **Bank Integration**: API connections to financial institutions (with proper security)

- **Mobile App**: Companion mobile application for iOS and Android



**User Experience**:



- **Themes**: Additional color schemes and light mode support

- **Customization**: User preferences and interface customization options

- **Notifications**: Transaction reminders and budget alerts

- **Accessibility**: Enhanced screen reader support and keyboard shortcuts



### Contributing Guidelines



1. **Code Standards**: Follow existing TypeScript and Svelte conventions

2. **Testing**: Include tests for new features and bug fixes

3. **Documentation**: Update README and add inline code comments

4. **Performance**: Ensure new features don't impact application speed

5. **Accessibility**: Maintain WCAG 2.1 compliance for all new UI elements



## 📄 License & Legal



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



### MIT License Summary



- ✅ **Commercial Use**: Use in commercial projects

- ✅ **Modification**: Modify and adapt the code

- ✅ **Distribution**: Share and distribute the application

- ✅ **Private Use**: Use for personal projects

- ❗ **Liability**: No warranty or liability from original authors

- ❗ **Attribution**: Include original license in distributions



## 🎯 Summary



**Enhanced Finance Tracker** is a comprehensive, modern web application that transforms personal finance management from a simple CLI tool into a sophisticated, feature-rich platform. Built with cutting-edge web technologies, it provides:



- **Complete Financial Tracking**: Income, expenses, and balance management

- **Advanced Analytics**: Interactive charts, spending insights, and trend analysis

- **Professional Interface**: Dark mode, responsive design, and accessibility compliance

- **Powerful Data Management**: CSV import/export, filtering, and bulk operations

- **Zero Server Dependency**: Fully client-side application with localStorage persistence

- **Production Ready**: Optimized builds and deployment configuration included



**Ready to use immediately**: Run `pnpm install && pnpm dev` and visit `http://localhost:5173` to start managing your finances with this powerful web application.



## 📋 Declaration of AI Use



I declare that I have used Google Gemini 2.5 Pro (large language model) as a tool to check for errors and bugs in my code and documentation, and for research purposes to understand different features and functionalities. The output generated by the AI was used as a guide and was critically reviewed, edited, and integrated into my work. All final content and ideas are my own.



This use of AI falls within the usage guidelines for AI tools as specified by SAE's academic integrity policies.



**Date**: 19 July 2025



---



**🚀 Start tracking your finances today with this modern, comprehensive web application!**