Budget Bee

What I Did

I built a complete, fully functional, local-first Personal Expense Tracker designed to help users manage their finances easily without requiring any complex setup or authentication.

Tech Stack:

• Frontend: React, TypeScript, Vite
• Backend: Node.js, Express
• Database: SQLite (persists data locally in a single file)
• Styling & Icons: Custom CSS, Lucide React icons, Recharts for visualizations

Key Features Implemented:

• Core CRUD Operations: Easily add, edit, list, and delete expenses with robust frontend and backend validation.
• Categorization & Tagging: Organize expenses into preset categories (Food, Transport, Bills, etc.) and add custom comma-separated tags.
• Filtering & Search: Find exactly what you need by filtering through categories, date ranges, titles, or specific notes and tags.
• Monthly Summary & Budgets: View a breakdown of your spending month-by-month. Set category-specific budget caps and visually track when you go over budget.
• Recurring Expenses: Automate your fixed monthly costs (like rent or subscriptions) to be added automatically.
• Data Portability: Seamlessly import and export your expense history via CSV.
• Visualizations & UX: Includes a dynamic bar chart for category breakdowns, a fully functional Dark Mode, and keyboard shortcuts (e.g., press N for a new expense).
• No Authentication: Designed strictly for single-user local use for maximum simplicity.

AI Tools Used

This project was built with the assistance of advanced AI coding tools to accelerate development and debug edge cases:

• Google Deepmind (Gemini / Antigravity): Acted as an autonomous pair programmer to help architect the SQLite database, implement React features, debug state issues, and write robust validation logic.
• ChatGPT & Claude: Provided quick problem-solving, code snippets, and explanations for complex architecture decisions.
• GitHub Copilot & Cursor: Accelerated boilerplate code generation, autocompletion, and context-aware editing.

---

How to Install and Run on ANY PC

Follow these steps to get the Expense Tracker running on any computer.

Prerequisites

You need to have Node.js installed on your PC.

1. Download and install Node.js from nodejs.org.
2. Verify the installation by opening your terminal (Command Prompt, PowerShell, or Terminal) and typing:

   node -v
   npm -v

   This should print the installed version numbers.

Installation Steps

1. Get the Code: Clone the repository using Git, or download the ZIP file and extract it to a folder on your PC.

   git clone https://github.com/ameeshmohd11/Expense-tracker-main.git
   cd Expense-tracker-main

2. Install Dependencies: Open your terminal inside the project folder and run:

   npm install

   This will download all the necessary packages for both the frontend and backend.

3. (Optional) Load Sample Data: If you want to test the app with some pre-filled sample expenses, budgets, and recurring items, run:

   npm run seed

4. Start the Application: Start both the React frontend and the Express backend simultaneously by running:

   npm run dev

5. Open the App: Open your favorite web browser and go to: http://localhost:5173

---

Project Structure

├── server.ts              # Express API routes
├── db/
│   ├── index.ts           # SQLite schema, queries, CSV handling, seeding
│   └── validate.ts        # Server-side validation logic
├── scripts/seed.ts        # Script to populate the database (npm run seed)
├── expenses.db            # SQLite database file (created automatically at runtime)
└── src/
    ├── App.tsx            # Main React application state and orchestration
    ├── components/        # UI Components (ExpenseForm, ExpenseList, Filters, etc.)
    ├── hooks/             # Custom hooks (useTheme, useKeyboardShortcuts)
    ├── types.ts           # TypeScript interfaces
    └── dateUtils.ts       # Date parsing and formatting helpers

Troubleshooting

• Port Conflicts: The backend API runs on port 3001 and the frontend runs on port 5173. Ensure no other applications are using these ports.
• "Authentication required" Error: If you see this from an older cached run, simply restart your terminal and run npm run dev again to ensure the latest server code is running.