.. _track_d_byod_gnucash:

===========================================
Track D BYOD with GnuCash (core_gl profile)
===========================================

GnuCash is a **free, open-source** double-entry accounting system. 

Note that in the commands below, replace <BYOD_DIR> with your project folder (for example: byod/gnucash_demo).

In Track D, we use it as a “real but accessible” source system:

- it produces realistic **multi-line split** exports (not toy spreadsheets)
- it teaches a *cleaning + normalization* lesson that matches real analytics work
- it requires **no trials** and works offline

What you’ll do
--------------

1. Create a tiny mock business in GnuCash (guided transaction list).
2. Export your transactions using **Export Transactions to CSV** with **Simple Layout OFF**.
3. Run the Track D BYOD normalization pipeline to produce:

   - ``normalized/chart_of_accounts.csv``
   - ``normalized/gl_journal.csv``

Downloads (demo pack)
---------------------

If you want to follow along quickly, download:

- :download:`Transaction list to enter in GnuCash <_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv>`
- :download:`Demo export (complex/multi-line) <_downloads/gnucash_demo/gnucash_demo_export_complex.csv>`

The export file above is **adapter-ready** (it matches what the ``gnucash_gl`` adapter expects).

Step 1 — Create a tiny GnuCash book
-----------------------------------

In GnuCash, create a new file (a “book”).

You can either:

- use a default “Small Business” chart of accounts, *or*
- create only the accounts you need (minimum below)

Minimum accounts used in the demo:

- ``Assets:Current Assets:Checking``
- ``Assets:Equipment``
- ``Liabilities:Credit Card``
- ``Liabilities:Sales Tax Payable``
- ``Equity:Owner Capital``
- ``Income:Sales``
- ``Expenses:Supplies``
- ``Expenses:Rent``
- ``Expenses:Shipping``
- ``Expenses:Advertising``

Step 2 — Enter the demo transactions
------------------------------------

Use the downloaded transaction list as your guide:

:download:`gnucash_demo_transactions_to_enter.csv <_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv>`

Tips:

- Most entries can be done in the **Checking** register.
- For the “sales tax” example, use a **split** transaction.
- For the credit-card equipment purchase, enter it in the **Credit Card** register.

Step 3 — Export from GnuCash (complex layout)
---------------------------------------------

Use:

``File → Export → Export Transactions to CSV``

Critical setting:

- **Uncheck** “Simple Layout” (this creates the multi-line export)

Export a CSV that includes your accounts and the date range that covers your demo transactions.

Step 4 — Initialize a Track D BYOD project
------------------------------------------

From any folder you like (your BYOD projects can live anywhere):

.. code-block:: console

   pystatsv1 trackd byod init --dest <BYOD_DIR> --profile core_gl

Need a reminder of options? Run: ``pystatsv1 trackd byod init --help``

This creates:

- ``tables/`` (where you place exports)
- ``normalized/`` (generated outputs)
- ``config.toml`` (tiny config: profile, tables_dir, adapter)

Step 5 — Point the project at the GnuCash adapter
-------------------------------------------------

Open:

``<BYOD_DIR>/config.toml``

Change:

.. code-block:: toml

   [trackd]
   adapter = "gnucash_gl"

(Leave ``profile = "core_gl"`` as-is.)

Step 6 — Place your export in the expected location
---------------------------------------------------

Copy your GnuCash export CSV to:

``<BYOD_DIR>/tables/gl_journal.csv``

Yes, the file is called ``gl_journal.csv`` even though it is still “raw export.”
The adapter reads this file and writes the canonical tables to ``normalized/``.

If you downloaded the demo export from this page (PyPI users), copy it into place:

.. code-block:: console

   # Windows (PowerShell)
   Copy-Item "<PATH_TO_DOWNLOADED_EXPORT_CSV>" (Join-Path "<BYOD_DIR>" "tables\gl_journal.csv")

   # Windows (Git Bash)
   cp "<PATH_TO_DOWNLOADED_EXPORT_CSV>" "<BYOD_DIR>/tables/gl_journal.csv"

   # macOS/Linux
   cp "<PATH_TO_DOWNLOADED_EXPORT_CSV>" "<BYOD_DIR>/tables/gl_journal.csv"

If you have the repo source code, the same demo export also lives here:

- ``docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv``

Step 7 — Normalize
------------------

Run:

.. code-block:: console

   pystatsv1 trackd byod normalize --project <BYOD_DIR>

   # (optional) override profile explicitly
   pystatsv1 trackd byod normalize --project <BYOD_DIR> --profile core_gl

You should now have:

- ``<BYOD_DIR>/normalized/chart_of_accounts.csv``
- ``<BYOD_DIR>/normalized/gl_journal.csv``

Step 8 — Validate the normalized tables
---------------------------------------

.. code-block:: console

   pystatsv1 trackd validate --datadir <BYOD_DIR>/normalized --profile core_gl

Step 9 — Do a first analysis
----------------------------

Go to:

- :doc:`track_d_byod_gnucash_demo_analysis` (daily totals + basic plots), or
- :doc:`track_d_my_own_data` (the general “apply Track D to your data” bridge)

Troubleshooting
---------------

- If normalization complains about missing columns, re-export and confirm **Simple Layout is OFF**.
- If numbers import incorrectly (decimal commas, etc.), adjust your export settings so amounts use a ``.`` decimal.