Personal Finance Tracker 🧾

Project Overview

The Personal Finance Tracker is a command-line application built to help users manage their personal finances by tracking income and expenses. It supports core operations such as adding, editing, deleting transactions and generating financial reports. The application is built using Kotlin and uses CSV file storage for persistent data management.

This application is designed to be simple, extensible, and reliable, with a focus on testing and clean code practices.

---

Features ✨

Transaction Management:

• Add, edit, and delete transactions: Provides functionality to manage your financial records easily.
• Transaction Validation: Ensures no invalid data (e.g., no negative amounts, duplicate transaction IDs).

Financial Reports 📊:

• Generate monthly financial reports: Summarizes income, expenses, and net balance for a given month.
• Generate reports for a custom date range: View financial data for any specified period.

Data Persistence 💾:

• Store transaction data in CSV files for long-term persistence: Ensures your data is saved between application runs.
• Load and save transactions using a flexible CSV-based approach: Simplifies file management without a database.

Test-Driven Development 🧪

This project follows a Test-Driven Development (TDD) approach.Test methods are defined in the /test directory and are designed to validate the business logic implemented in the main source code.

• Each core functionality (e.g., add/edit/delete transaction) has its own dedicated set of tests.
• A custom check(actual, expected) helper function ensures clear output on test success/failure.
• Continuous Testing with GitHub Actions : Automated tests are executed on every pull request and push using GitHub Actions to ensure the integrity and stability of the codebase.

Dependency Inversion Principle (DIP) And Dependency Injection (DI) 🔄 💉

The project uses this Principles in classes (InMemoryDatasource,CSVDatasource,TransactionRepositoryImpl) as below :

1. Interface For Local Data source :

interface LocalDatasource {
    fun addTransaction(transaction: Transaction): Boolean
    fun deleteTransaction(id: Int): Boolean
    fun editTransaction(transaction: Transaction): Boolean
    fun getAllTransactions(): List<Transaction>
    fun getTransactionById(id: Int): Transaction
    fun getMonthlyReport(date: LocalDate): Report
    fun getTransactionsByDateRange(startDate: LocalDate, endDate: LocalDate): List<Transaction>
}

2. A classes inherit from interface:

class InMemoryDatasource : LocalDatasource {}
class CSVDatasource(private val csvFileHandler: CsvFileHandler) : LocalDatasource {}

3. class have constructor parameter type LocalDatasource:

The class parameter accepts objects from InMemoryDatasource and CSVDatasource classes

TransactionRepositoryImpl(private val datasource: LocalDatasource) : TransactionRepository {}

Create objects:

val datasource: LocalDatasource = InMemoryDatasource()
val repo = TransactionRepositoryImpl(datasource)

---

Installation ⚙️

Prerequisites

• Java 21 or higher ☕
• Kotlin 1.9 or higher 🛠️
• Gradle (wrapper included) ⚡

Steps to Install

1. Clone the repository:

   git clone https://github.com/Beijing-Squad/PersonalFinanceTracker.git
   cd PersonalFinanceTracker

2. Build the project:

   ./gradlew build

3. Run the application 🚀:

   To run the project from the terminal:

   ./gradlew run

4.Test Command

  ./gradlew test

Alternatively, you can run the main class directly through the IntelliJ IDEA if you prefer.

---

Usage 🎯

Command-Line Operations

The project is designed to be used via the command line. After running the application, you will interact with the system through a series of menu options or commands.

Command-Line Menu :

======================
PERSONAL FINANCE TRACKER
======================
1. Add Transaction
2. View Transactions
3. Edit Transaction
4. Delete Transaction
5. Generate Monthly Report
0. Exit
======================

Transactions View :

1. View All Transactions 
2. View Transactions By Date 
3. View Transactions By ID