FinanceBuddy/README.md

FinanceBuddy -- money on your Kanboard cards

Attach a money value to each board card, see it on the card, and total it per column, so a Kanboard project can double as a simple, visual finance board -- bills, installments, income vs expenses.

FinanceBuddy is opt-in per board: installing it changes nothing until a project manager enables it for a specific board under Settings -> Integrations. Boards that are not enabled look exactly as before.

The idea: a bill-lifecycle board

Kanboard imposes no structure, so FinanceBuddy fits one rather than dictating it. A layout that works well:

• Columns = a bill's status: Templates -> Due this month -> Paid. Cards flow left to right as they are paid.
• Tags = category: housing, utilities, comms, food...
• Due date = the bill's due date; color/priority = urgency.
• Each card carries a money value and, optionally, an installment count.

Recurring monthly bills can live as template cards spawned each month by the companion RecoReco plugin; FinanceBuddy only owns the money.

What it does

Once a board is enabled:

Set the money on a card

The task edit/create form gains a Finance section in the middle column:

• Amount in R$.
• Debit or Credit (money out vs money in).
• Installment current / total (for example 2 of 10). Leave the total blank for an open-ended recurring bill.

See it on the card

A badge appears just under the card title -- both on the board and at the top of the opened card, so the money is visible whether you glance at the board or read the card (no need to open the edit form):

• red with a - for a debit, green with a + for a credit (both the color and the sign carry the meaning, and the badge's own background stays readable on any card color);
• followed by pN/M when a total is set (for example p2/10), hidden for open-ended bills.

Total per column

Each column header shows a Total: of its cards -- credits positive, debits negative (the net): red when negative (what you owe), green when positive, gray at zero. It is shown for every column, including Total: R$0,00.

Installments and recurrence

FinanceBuddy carries the money across copies. Kanboard's built-in recurrence and RecoReco's calendar recurrence advance the installment on the next occurrence (p2/10 -> p3/10); a manual duplicate copies it as-is. When a RecoReco-followed plan finishes, the parked template is left one past the last installment (p3/3 -> p4/3) as a "plan complete" marker that RecoReco reads to stop recurring; the copies themselves still read p1/3 .. p3/3. Open-ended plans (blank total) keep counting.

Money format

Amounts show in R$ with a comma decimal and no thousand separator (for example R$1234,56). Input accepts either a dot or a comma as the decimal separator, so 1234.56 and 1234,56 are the same value.

How it stores data

No database migration. The per-board enable flag is stored in project metadata; each card's money is stored in task metadata. The finance fields live in the normal task form but are saved separately (they are not task columns), so ordinary task saving is untouched. Uninstalling the plugin leaves that metadata harmlessly in place and changes nothing else.

Requirements

• Kanboard >= 1.2.0

Installation

Copy this folder into your Kanboard installation as plugins/FinanceBuddy/. The directory name must be exactly FinanceBuddy (Kanboard derives the plugin namespace from the folder name). No build step and no database migration. Then, on each board you want to track, go to Settings -> Integrations and tick "Enable FinanceBuddy on this board".

License

AGPL-3.0. See LICENSE.

More Kanboard plugins by Ruben (drbeco)

All free and AGPL-3.0, at code.beco.cc:

• RecoReco -- calendar-scheduled recurring cards (yearly, monthly, weekly, daily), driven by the card due date. Pairs directly with FinanceBuddy: recurring bills spawn on schedule and their installments count down until the plan is paid off.
• OrganonTweaks -- an umbrella of small quality-of-life board tweaks: remove an empty column, always show the comment icon, emphasize due dates, extra search keywords and shared board filters, and more.
• BulkMoveTasks -- move every task from one board column to another in a single action.
• ShrinkVertically -- shrink vertically-collapsed board columns so the horizontal scrollbar stays within reach.
• TweakDrag -- board drag and touch niceties: drag-to-scroll, a wider column gap, and smoother card dragging.