This repository contains the full dashboard and configuration that I use to keep track of my personal finances: transactions, investments, and savings.

Feel free to fork or copy this repository. The importers I have added are based on Beancount Red's Importers. However, I did not require most of the features and preferred not to use it as a submodule due to lack of personalization, so I re-used some of the work.

This project makes use of Beancount v3, and the way it is done is not compatible with v1 and v2.

---

Repository Structure

The repository is structured following the recommended Beangulp file organization tree, splitting into different directories: ledgers, documents, and importers. In this case, the importers are part of the public source code of the project and remain as content of this repository. However, the ledgers and documents directories are private and should be created and structured by each user as they see fit.

Key Components

• config.py: Main Beancount entry point where importers are initialized. This is the script to be executed in Beancount v3.
• ledger/: Directory where all the output ledgers from Beancount are stored. This is personal to each user, and you can structure it as you prefer.
• documents/: Directory where all the received and downloaded data from different institutions is saved. Some users might prefer to keep this directory out of source control.
• src/:
  • importers: Custom importers implementation for banking, transactions, or institutions I use. Avoid including personal information here.
  • readers: Generalization of modules used to read and parse typical files from banking institutions.
  • transactions: Generalization of modules used to parse typical data from banking institutions into Beancount transactions.
  • utils: Other helpers or extra tools.
• tests/: This directory contains examples of real downloaded files (anonymized) from institutions of all the configured importers that will serve as regression tests. Next to each downloaded file is a .bean golden file with the correct contents extracted by the importer. These should be generated by the generate command from the importer and reviewed for correctness. Running the test command after a change to your importer code will verify the importer's updated output against the existing golden files.

Example Internal Structure

Below is an example of how the repository structure might look:

Personal-Finances/
├── config.py
├── ledger/
│   ├── 2025/
│   │   ├── january.bean
│   │   ├── february.bean
│   │   └── ...
│   └── main.bean
├── documents/
│   ├── bank_statements/
│   │   ├── bank1_statement.pdf
│   │   ├── bank2_statement.csv
│   │   └── ...
│   ├── receipts/
│   │   ├── receipt1.jpg
│   │   └── receipt2.jpg
│   └── ...
├── src/
│   ├── importers/
│   ├── readers/
│   ├── transactions/
│   └── utils/
└── tests/
    ├── bank1_statement.csv
    ├── bank1_statement.bean
    └── ...

---

Initial Setup

To set up the repository for your personal use, follow these steps:

1. Clone the Repository:

   git clone --recurse-submodules https://github.com/ItsShunya/Personal-Finances.git
   cd Personal-Finances

2. Install Dependencies: Ensure you have Python 3.13+ installed. Then, install the required Python packages:

   • Using uv:

   uv sync

   • Using pipenv:

   pipenv install
   

3. Set Up Directories: Create the ledger/ and documents/ directories if they do not already exist:

   mkdir ledger documents

4. Configure Importers: Edit the config.py file to initialize the importers for your specific institutions. Refer to the examples in the src/importers/ directory. You can use there or create your own.

5. Run Tests (Optional): Verify that the importers are working correctly by running the tests:

   uv run config.py test ./tests > ./ledger/tmp.beancount

---

How to use

1. Download Transactions or Statements: Begin by downloading transaction or statement files from your banking institutions. Save these files in the documents/ directory under appropriate subfolders (e.g., bank_statements/).

2. Configure Importers: Edit the config.py file to configure the necessary importers to read and parse the downloaded documents. Refer to the examples in the src/importers/ directory for guidance.

3. Verify Importers: Run the following command to check if the importers correctly detect the added files:

   uv run config.py identify ./documents

4. Extract Transactions (First Time): For the first run, extract transactions from the documents and save them to a temporary ledger file:

   uv run config.py extract ./documents > ledger/tmp.bean

   Open the tmp.bean file and manually classify the transactions into different categories. This step ensures that your ledger is properly organized.

5. Configure Smart Importers (Optional): To streamline future imports, you can configure the importers to be smart importers. These use machine learning to augment Beancount's capabilities, enabling automatic detection of output categories. This step is optional but highly recommended for efficiency.

6. Extract Transactions (Future Runs): For subsequent runs, use the following command to extract transactions while leveraging the augmented machine learning classification:

   uv run config.py extract -e ./ledger/main.bean ./documents > ledger/tmp.bean

   Replace main.bean with the path to your main Beancount ledger file. This will ensure that the importers use the existing ledger data to improve classification accuracy.

---

Dashboards (Fava)

Fava is a web interface for Beancount that provides an intuitive way to visualize and manage your personal finances. In this project, Fava dashboards can be used to track income, expenses, account balances, and investments over time. Different sections of the dashboard allow you to analyze trends, view detailed transaction histories, and generate reports such as income statements or balance sheets. Additionally, Fava's budgeting tools and customizable charts make it easier to monitor financial goals and identify spending patterns.

To run your dashboards simply use:

uv run ledgers/main.bean

replacing main.bean with your main beancount ledger file.

---

Continuous Integration (CI)

Github Actions could be used in this project to automate testing, ensure code quality, and streamline deployment processes. For example, CI could automatically run beangulp tests on every commit to verify that changes to importers or configurations do not break existing functionality. While CI/CD pipelines are not yet implemented, they are within the scope of future development to enhance reliability and maintainability

---

Contributing

While this repository is primarily for personal use, I welcome constructive feedback, tips, and suggestions. If you notice areas for improvement or have ideas for better practices, feel free to open an issue or reach out.

---

License

This repository is shared under the Apache-2.0 License. You are free to use and modify the code, but please give credit where it's due.

---

Acknowledgments

Special thanks to the Beancount community for their work, as well as to redstreet for the work on his importers.