From 6cbfe765efe0eea613879698f7a369ff81f49fb2 Mon Sep 17 00:00:00 2001 From: Keith Solomon Date: Mon, 10 Feb 2025 09:15:39 -0600 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=84=20docs:=20Update=20readme=20#skipG?= =?UTF-8?q?A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 151 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 117 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 768fa54..d53685f 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,133 @@ # BillTrak -BillTrak is a web application designed to help users manage and track their bills. It provides features to add, edit, and view bills, as well as visualize year-to-date (YTD) amounts using charts. +## Project Title +BillTrak - A Simple Bill Tracking Web Application + +## Description +BillTrak is a lightweight, web-based application designed to help users manage and track their bills and payments. It provides an intuitive interface for adding, editing, and viewing bills, along with visualizations of year-to-date spending through interactive charts. ## Features +- **Bill Management**: Add, edit, and view bills with details like date, payee, amount, payment ID, and comments +- **Payee Management**: Add and manage payees (bill recipients) +- **Yearly Overview**: View bills by year with sorting options (date, payee) +- **Visual Analytics**: Interactive pie chart showing year-to-date spending distribution +- **Dark Mode**: User-friendly dark mode toggle for comfortable viewing +- **Responsive Design**: Works seamlessly across devices +- **Data Persistence**: SQLite database for reliable data storage -- Add new bills and payees -- Edit existing bills -- View bills by year and sort them -- Display YTD amounts and visualize them using a pie chart -- Dark mode toggle for better user experience +## Installation -## Technologies Used +### Prerequisites +- Docker and Docker Compose installed +- Basic understanding of web applications -- HTML, Tailwind CSS, JavaScript -- Chart.js for data visualization -- Docker for containerization +### Steps +1. Configure the `docker-compose.yml` file: + ```yaml + services: + app: + container_name: BillTrak + restart: unless-stopped + image: ghcr.io/solo-web-works/billtrak:main + + ports: + - "8888:80" # Map port 8888 on the host to port 80 in the container. Change the left side to change the host port. + + volumes: + # Mount the current directory for live development + # - .:/var/www/html + - ./data/bills.db:/var/www/html/data/bills.db # Bind mount to persist SQLite data + ``` + +2. Set up the database: + ```bash + cp bills-sample.db ./data/bills.db + ``` + +3. Start the application using Docker: + ```bash + docker-compose up -d + ``` + +4. Access the application at: + ``` + http://localhost:8888 + ``` ## Usage +1. **Adding a Bill**: + - Fill out the "Add New Payment" form with date, payee, amount, and optional details + - Click "Add Bill" to save -1. Copy the `bills-sample.db` file to `bills.db` in a folder docker can access. This will be the SQLite database used to store bill data. +2. **Adding a Payee**: + - Use the "Add New Payee" form in the sidebar + - Enter the payee name and click "Add Payee" -2. Start the container using `docker compose up -d` with the following `docker-compose.yml` configuration: -```yaml -services: -app: - container_name: BillTrak - restart: unless-stopped - image: ghcr.io/solo-web-works/billtrak:main +3. **Viewing Bills**: + - Bills are automatically displayed for the selected year + - Use the sort dropdown to organize bills by date or payee - ports: - - "8888:80" # Map port 8080 on the host to port 80 in the container. Change the left side to change the host port. +4. **Editing a Bill**: + - Click the "Edit" button on any bill + - Modify the details in the popup modal and click "Save" - volumes: - # - .:/var/www/html # Mount the current directory for live development - - ./data/bills.db:/var/www/html/data/bills.db # Persist SQLite data -``` -3. Access the application at http://localhost:8888 +5. **Viewing Analytics**: + - The YTD Chart section shows a pie chart of spending distribution + - The YTD Summary displays total amounts by payee + +## Configuration +The application can be configured through the following methods: + +1. **Port Configuration**: + Modify the `docker-compose.yml` file to change the host port: + ```yaml + ports: + - "8888:80" # Change 8888 to your preferred port + ``` + +2. **Database Configuration**: + The SQLite database file is located at `data/bills.db`. This location should be bind mounted in your compose file for data persistence. + +3. **Environment Variables**: + Add environment variables to the `docker-compose.yml` file for advanced configuration: + ```yaml + environment: + - PHP_ERROR_REPORTING=E_ALL + - PHP_DISPLAY_ERRORS=On + ``` + +## Contribution Guidelines +We welcome contributions! Please follow these steps: + +1. Fork the repository +2. Create a new branch for your feature/bugfix +3. Commit your changes with clear, descriptive messages +4. Submit a pull request with a detailed explanation of your changes + +Please ensure your code follows the existing style and includes appropriate documentation. + +## Testing +The application includes basic functionality testing: + +1. Start the application using Docker +2. Open the application in your browser +3. Test all features: + - Add, edit, and delete bills + - Add new payees + - Verify chart updates + - Test sorting functionality + - Verify dark mode toggle + +## Acknowledgements +- **Chart.js** for data visualization +- **Tailwind CSS** for styling +- **PHP** and **SQLite** for backend functionality +- **Docker** for containerization and easy deployment ## Roadmap +- [ ] Implement user authentication +- [ ] Add CSV import/export functionality +- [ ] Implement bill reminders and notifications +- [ ] Add advanced reporting features -- Add feature to import bills from CSV files -- Add feature to export bills to CSV files -- Add authentication and user accounts -- Add notifications for upcoming bills -- Got an idea? Open an issue! - -## Contributing - -Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes. +For feature requests or bug reports, please open an issue on (GitHub)[https://github.com/Solo-Web-Works/BillTrak/issues].