Entropy for Firefly III

Live demo → — 100% synthetic data, no Firefly III instance behind it.

What's still outstanding — overdue and upcoming, in one place.

Firefly III records every transaction you've made and knows all your recurring ones — rent, salary, that streaming subscription. But it won't lay the recurring ones out in front of you and tell you which are quietly overdue and which are still ahead.

Entropy for Firefly III does exactly that. It's a read-only view that complements Firefly III: point it at your instance, and it projects every recurring transaction forward, matches each expected occurrence against your real booked transactions, and then shows you only what's left — the outstanding set.

Two views, and they answer opposite questions:

View	Question	Reads
Outstanding & Upcoming	what is coming, and what quietly slipped	your recurring transactions, projected
Reports	what actually happened over a window	your booked transactions, ranked

Both are read-only. Entropy writes nothing back to Firefly III, ever.

Every occurrence you see is in one of two states:

Status	Meaning
Upcoming	Due in the future. Nothing to do yet. Finite installments show how many payments remain.
Needs review	Its date has passed and no payment accounts for it.

When an occurrence does match a real transaction, it's confirmed — and it simply drops out of the view. Entropy shows what's outstanding, not what's already done: the done half already lives in Firefly III, and Entropy doesn't restate it.

"Needs review" is the point of the whole thing. Entropy for Firefly III never guesses. It marks an occurrence paid by the account that paid it, not the amount — so a recurring transaction whose amount drifts, or that you paid late or in the next month, still counts; each real payment clears the earliest still-open occurrence. If nothing accounts for an occurrence once its date has passed it says so, and if a payment can't be attributed cleanly (a shared or noisy account) it flags it — instead of pretending either way.

Credit-card installments (parcelado)

An installment lives in Firefly III the moment it is charged: a real card withdrawal, dated on the statement, carrying its own parcela number (installment N/M in the description, or an installment:<total>:<current> tag). Entropy keeps no parallel forecast object for it — that second copy fired on a different day, fell into a different billing cycle, and double-counted the current month. Instead the forecast is a pure function of the booked charges: it reads the latest parcela of each active plan (off the last closed statement, plus brand-new plans off the still-open one) and projects only the unbilled tail, parcelas N+1 … M, onto the coming statement dates. A charge already in the ledger is never also projected, so an installment can never be counted twice.

Nothing is inferred. The total M and number N come from the charge itself; a charge that states no installment is an ordinary one-off and is never projected, and a plan whose total is unknown projects nothing. Concurrent identical plans stay distinct (three 8/12 charges are three plans). Past the last issued statement the exact date isn't known, so the tail falls monthly and is flagged cycle_projected.

Open-ended card charges — a subscription with no finite N — are the exception: they are recurrences, and they still clear against the paid billing cycle below.

Card billing cycles

A card statement covers the previous cycle: charges up to a closing date, paid a week or so later. So the month a fatura is paid in tells you nothing about which charges it covered, and the closing day is the issuer's choice — one real card closed on the 10th one month and the 13th the next. Entropy therefore does not compute cycles. It reads them from the card account's notes in Firefly III, one row per fatura, exactly as the statement prints them:

cycle: close=2026-06-10 due=2026-06-20 total=21788.40
cycle: close=2026-07-13 due=2026-07-20 total=26139.84

total is optional; when present, the payload reports how much of it the recurring charges accounted for, so an over- or under-clear is visible. Each fatura also prints the next closing date, so the table can always be kept one cycle ahead.

A settlement (a transfer into the card described as a payment) clears the earliest still-unpaid cycle that had already closed when it was made and whose successor was not yet due. A payment late by up to a full cycle still counts; a minimum paid days before the full payment is absorbed rather than counted twice; and an on-time payment can't quietly absorb a cycle you skipped.

A card with no cycle rows clears nothing — its occurrences stay outstanding, flagged cycle_unknown. Unknown is reported, never guessed.

This is the beginning of the README. Read the rest at the original. Read the full README ↗