refactor(categorisation): flatten the category taxonomy to 27 direction-filtered categories

[suiramdev]

Summary

Replaces the 75-category, 16-group hierarchy with 27 categories under three sections — income, investments, spending. The picker now filters by the transaction's direction: 20 categories on an outgoing transaction, 10 on an incoming one. Start with packages/api/src/lib/taxonomy.ts; every other change follows from it. No migration: the decoder reads an old slug on the way out.

Motivation

• A topic taxonomy made every signal guess which of sixteen shelves a merchant sat on, and made the reader learn them.
• Offering salary on a card payment was the largest single source of wrong picks; direction is already known from the sign.
• Insurance was a category competing with the thing insured, so the same policy landed in two places depending on the signal that found it.
• An internal transfer was both a category and a boolean column, and the two could disagree.

Drawbacks

• 27 categories lose precision the old set carried: flights, accommodation and taxi all become transport-travel. A reader who used the fine grain loses it.
• Stored slugs are never rewritten, so LEGACY_CATEGORY_SLUGS (70 entries) has to stay until a data-* release is rebuilt from the new taxonomy.
• Custom-category budget lines fold into their section's fallback in the two re-keyed charts.
• The jev provider's group question drops from 17 options to 4 while its spending leaf question grows to 16; the 0.5 joint-probability floor was not retuned for that shape.

Prior art

• 20260831120000_category_hierarchy did the opposite move with a SQL remap; this one relies on the read-path decoder instead, so no downgrade is one-way.
• Colour and icon already existed per group; moving them per category reuses categoryColor and categoryIcon unchanged.
• TAXONOMY_VERSION already existed for exactly this case and goes to 2, invalidating the classification cache.

Notes

• Visual change: category pickers, the spending donut, budget-vs-actual, and the settings category list.
• No migration added. lookupUserOverride no longer casts merchant_override.category; proved against a seeded stale row, and mutation-checked against the raw cast.
• Tests: deterministic.test.ts gains readsAsRefund direction cases and a rule that no word naming a movement names a category; mcc-categories.test.ts, transaction-category.test.ts and jev.test.ts re-grounded on the new slugs.
• Docs updated: guides/categories, concepts, integrations/procedures, contributing/categorisation, contributing/data-model, plus docs/engineering/{api,categorisation,data-pipeline}.md and packages/api/data/README.md. The data-model migration table was two rows stale and is corrected.
• Rebased onto feat: pluggable transaction classifier, and a sync that reports its progress #36; the classifier and sync-progress work landed mid-change, and the keyword tables, MCC ranges and jev fixtures were reconciled with it rather than reverted.
• Verified in a browser on a clean stack: 20/10 picker rows, Sankey and donut keyed by category, override decode.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: c19f4870-24d4-4222-880c-f1597e11b4e5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}