Billzilla

A web application to simplify managing shared expenses for groups, with a key feature for adding expenses via voice commands.

---

Table of Contents

• Project Description
• Tech Stack
• Getting Started Locally
• Available Scripts
• Project Scope
• Project Status
• License

---

Project Description

Billzilla is a responsive web application designed to simplify the management of shared expenses among groups such as friends, roommates, or families. The application allows users to easily track, split, and settle costs. A key distinguishing feature is the ability to add expenses using voice commands, which intelligently processes speech into structured data and fills out the form, requiring only user approval. Authentication is handled through secure email and password registration with email verification for account security.

The project aims to solve common problems associated with shared finances, such as manual tracking difficulties, complex calculations for unequal splits, and the risk of misunderstandings due to forgotten expenses.

Tech Stack

The project is built with a modern tech stack:

• Framework: Astro 5
• UI Library: React 19
• Language: TypeScript 5
• Styling: Tailwind CSS 4
• Component Library: Shadcn/ui
• Unit Testing: Vitest with React Testing Library
• E2E Testing: Playwright
• CI/CD: GitHub Actions
• Test Coverage: @vitest/coverage-v8

Getting Started Locally

To set up and run the project on your local machine, follow these steps:

Prerequisites

• Node.js version 22.14.0 (as specified in the .nvmrc file). We recommend using nvm to manage Node.js versions.

Installation

1. Clone the repository:

   git clone https://github.com/wojciech-borek/billzilla.git
   cd billzilla

2. Set the Node.js version: If you are using nvm, run the following command in the project root:

   nvm use

3. Install dependencies:

   npm install

4. Set up environment variables: Create a .env file in the root of the project by copying the example file:

   cp .env.example .env

   Then, fill in the necessary environment variables in the .env file (e.g., Supabase credentials for database and authentication).

5. Run the development server:

   npm run dev

   The application will be available at http://localhost:3000.

Available Scripts

The following scripts are available in package.json:

Script	Description
npm run dev	Starts the development server.
npm run build	Builds the application for production.
npm run preview	Previews the production build locally.
npm run astro	Runs the Astro CLI.
npm run lint	Lints the codebase for errors.
npm run lint:fix	Fixes linting errors automatically.
npm run format	Formats the code using Prettier.
npm run test	Runs unit tests in watch mode.
npm run test:unit	Runs unit tests in single run mode.
npm run test:ui	Opens Vitest UI for interactive testing.
npm run test:coverage	Generates test coverage report.
npm run test:e2e	Runs all E2E tests in headless mode.
npm run test:e2e:ui	Opens Playwright UI for test debugging.
npm run test:e2e:headed	Runs E2E tests with visible browser.
npm run test:e2e:debug	Runs E2E tests in debug mode.
npm run test:e2e:update-snapshots	Updates E2E test snapshots.

Project Scope

Key Features

• User and Group Management:

  • Secure sign-up and login with email and password authentication.
  • Email verification for account security.
  • Password reset functionality.
  • Create and name new expense groups.
  • Invite others to groups via email.
  • Ability to leave a group at any time (financial data is preserved for final settlements). [Planned for future release]

• Expense Management:

  • Add expenses via a manual form (description, amount, date, currency).
  • Voice-powered Expense Entry: Add expenses using natural language voice commands.
  • Support for both "equal" and "specific amount" splits.
  • Real-time validation to ensure split amounts match the total expense.
  • Only the expense creator can edit or delete their entries.

• Balances and Settlements:

  • Automatic calculation and updating of balances within each group.
  • Clear summary of who owes whom, presented in the group's base currency.
  • "Settle Up" feature to log full or partial debt repayments.

• Currency Management:

  • Define a base currency for each group.
  • Add other currencies with manually set, fixed exchange rates against the base currency.

Out of Scope (for MVP)

The following features are intentionally excluded from the initial MVP release to focus on core functionality:

• Automatic fetching of currency exchange rates from external services.
• Complex user roles and permissions within groups.
• Push notifications for new expenses or balance changes.
• Data export functionality.
• Ability to attach images or receipts to expenses.

Project Status

Version: 0.0.1

The project is currently a work-in-progress. Core features are under active development.

License

This project is licensed under the MIT License. See the LICENSE file for more details.