How I designed permissions people can actually understand (Node + Prisma)

In most companies I've worked with, nobody can answer a simple question about the shared drive: who can see this folder, and why? Access is granted person by person, inherited in ways nobody remembers, and never cleaned up.

While building SpiderFolio, an open-source, self-hosted document management system for small businesses (https://github.com/spiderjad/SpiderFolio), I set one rule: every folder, file and page must show who has access and the reason, for example "Quality department · inherited from /Procedures".

Grant access to departments, not people

Access is given to departments and roles. When someone moves from Production to Quality, their access changes on its own. Direct grants to a person still exist, but the admin panel flags them as a sign of disorder.

Four levels, highest wins

MANAGE > EDIT > COMMENT > VIEW. A person collects every non-expired grant given to them and to their departments (including parent departments). If several apply, the highest level wins.

Inheritance you can cut

Folders, files and pages form one tree. By default a node inherits its parent's access up to the space. Any node can stop inheritance, so a "Payroll" folder inside "HR" can be locked down without touching the rest.

One function, explained

All of this lives in a single resolveAccess function backed by a table of test cases. Instead of returning only a level, it also returns the reason for each grant. That's what powers the "Share" dialog and the "who can see this?" report. Trees are resolved in batches, one query per level, to avoid N+1 queries, and cached per request.

Isolation first

Every query goes through a tenant-scoped Prisma client, and an integration test checks that a user from company A gets a 404 on every endpoint for company B's data.

SpiderFolio is AGPLv3 and installs with Docker Compose. Docs: https://spiderfolio.spiderjad.com/en/docs. I'd love feedback on this design.