Documents: a real category/folder tree instead of two flat filter rows

[ulsklyc]

Moved here from issue #762 so that feature ideas live where the rest of the backlog is discussed. Originally proposed by @EliseAkimie - full original wording and screenshot in #762.

The observation. The Documents module currently offers two separate, flat mechanisms side by side: categories as filter pills at the top, folders as a filter list in the sidebar. Both act as filters over one flat list, so selecting either only narrows the same list, which never changes shape. Nothing in the UI shows the relationship between them, even though a document's own breadcrumb ("Maison > Appartement") makes it clear that the category is the parent and the folder the child.

The suggestion. Turn the sidebar into a real hierarchical tree, Windows-Explorer style: categories at the top level with their folders nested underneath as expandable children. Clicking a category or a folder navigates into it, with a breadcrumb, showing only the documents inside instead of re-filtering the same flat list in place. "All documents" stays as it is: the flat, unfiltered view of everything.

Why it is worth considering. As filters, categories and folders are easy to miss and feel disconnected from each other: you have to know they exist, and you have to look in two separate UI zones. A tree with click-to-navigate would make the actual structure the primary way of finding a document, closer to how a file browser behaves.

Discussion welcome, in particular on whether the tree should replace the pills or sit next to them.

[ulsklyc]

Coming back to this with what the data model actually says, because it changes the question.

Categories and folders are not parent and child. They are two independent axes.

• category is a fixed list of 14 translated keys in the frontend (medical, school, identity, insurance, finance, home, vehicle, legal, travel, pets, warranty, taxes, work, other). It is not a table, it is a column on the document.
• family_document_folders is a table with id, name UNIQUE, created_by. No parent_id, and no reference to a category. Folders are flat and global.
• A document carries both: category (text) and folder_id (FK, nullable).

So nothing in the schema says a folder belongs to a category. A folder "Apartment" can - and in practice will - hold documents categorised home, insurance and legal at the same time.

That means the tree as originally described cannot be built from the data as it stands. Nesting folders under categories would either show the same folder under three different parents, or force a relationship that does not exist and would have to be invented at migration time - with no correct answer for a folder whose documents span several categories.

The breadcrumb in @EliseAkimie's screenshot ("Maison > Appartement") reads like a hierarchy, but it is showing two independent labels of one document side by side, not a path.

So the real question is one level earlier, and it is worth answering before any UI work:

(a) Make the hierarchy real. Give folders a parent_id and let them nest freely, and demote categories to what they actually are - a tag on the document. Then the sidebar is a genuine tree of folders, click-to-navigate with a real breadcrumb, and the category chips stay on top as a cross-cutting filter ("show me everything medical, wherever it lives"). This is the file-browser model, and it is the one that matches how people describe the problem.

(b) Keep both axes flat and fix the presentation instead. The complaint that categories and folders are "easy to miss and feel disconnected" is fair even without a tree: they sit in two separate UI zones with nothing relating them. Putting both in one place, and showing which combinations actually contain documents, addresses most of the pain for a fraction of the work.

I lean towards (a), because "a folder inside a folder" is what people ask for eventually and the current flat table has no answer for it - but it is a migration on a table that holds real documents, so it deserves to be a deliberate decision rather than a side effect of a sidebar redesign.

@EliseAkimie - when you described a Windows-Explorer tree, were you picturing folders inside folders (a), or mainly wanting the two existing lists to stop feeling disconnected (b)? Those lead to quite different amounts of work, and your answer decides which.

[EliseAkimie]

Thank you for taking the time to look into this and for such a detailed explanation. I really appreciate your feedback and the way you broke down the two options.

I was indeed picturing something more like option (a), with folders inside folders, similar to the Windows Explorer structure. Personally, I think that would work best for me and would feel much more intuitive to use.

Thanks again for taking the time to dig into this!