I Thought Permissions Were Simple. Then Teams Showed Up.

Chiankem Macbrain — Mon, 03 Aug 2026 08:23:07 +0000

I thought permissions would be one of the easiest parts of building TaskForge.

Create roles. Assign permissions. Done. Ship it, move to the next feature.

That assumption survived until the moment a second person joined a project. Then every action became a question nobody had actually answered yet: who can assign this? Who can archive it? Who can reopen something that's already marked complete?

The code was never the hard part. Agreeing on the rules was.

The problem with a flat role check

TaskForge is multi-tenant: Organization → Workspace → Team → Project. Early on, the natural instinct is something like:

if ($user->role === 'manager') {
// allow the action
}

That works right up until a single user is a Manager in one workspace and just a Member in another. A flat, global role check has no way to represent that — the same person needs different standing depending on where they are, not just who they are. Permissions turned out to be contextual, not global, and that realization changed the rest of the architecture.

Separating roles from permissions

Instead of hardcoding role checks everywhere, we split the concepts apart. A role grants permissions — it isn't itself the check.

Manager
↓
project.create
project.update
project.archive

Rather than sprinkling if ($role === 'manager') across the codebase, every action checks for a specific permission. Roles become a convenient bundle of permissions, not the source of truth for what's allowed.

Killing magic strings

Once permissions became strings like 'project.create' and 'project.archive', they started showing up everywhere — controllers, policies, Blade views. Any typo silently fails. Any rename means hunting through the whole codebase.

The fix was a dedicated permission constants class:

class ProjectPermissions
{
const CREATE = 'project.create';
const UPDATE = 'project.update';
const ARCHIVE = 'project.archive';
}

Small change. Big payoff — autocomplete, refactor safety, and one source of truth instead of a string scattered across the app.

Keeping policies thin

This was probably the decision with the most leverage. It's tempting to let a Policy do everything — check permissions, run business logic, maybe touch the database. We stopped that early, before Policy classes turned into 300-line files.

A Policy answers exactly one question: is this allowed? Nothing else. The actual how — creating the project, updating records, firing events — moved into dedicated Action classes: CreateProjectAction, UpdateProjectAction, DeleteProjectAction. Permissions decide whether something can happen. Actions decide how it happens. Mixing those two concerns is what turns authorization code into something nobody wants to touch six months later.

Authorization has to know where it is

The real fix wasn't just separating roles from permissions — it was making every check context-aware:

$user->canProjectPermission(
ProjectPermissions::UPDATE,
$project
);

"Can this user edit a project?" is an incomplete question. The real question is: can this user edit this project, inside this workspace, under this organization? Because a project belongs to a workspace, which belongs to an organization, authorization naturally follows that same hierarchy instead of checking each level independently — which is exactly the kind of inconsistency that creeps in if you're not careful.

The mistake that cost the most time

Early on, it felt reasonable to give every team its own role: Owner, Admin, Manager, Team Lead, Developer, QA, Guest. Within a week, nobody — including me — could reliably say which role actually had which permission.

Roles should stay few. Permissions grow. That imbalance is easy to miss until you're staring at seven roles trying to remember what Team Lead can do that Developer can't.

The actual lesson

None of this was a Laravel problem. Laravel's authorization primitives (can(), Gates, Policies) are fine on their own. The lesson was architectural: permissions aren't a user-management feature bolted onto the side of an app. They're part of the domain model. Treat them like middleware and they'll hold up for a while, then quietly become unmaintainable the moment real teams and real hierarchy show up. Treat them like a business capability from the start, and the system scales with the organization instead of fighting it.

I'm building TaskForge — an operational collaboration platform for teams and agencies — in public, and writing/recording about the actual engineering decisions behind it as they happen. No tutorials, no toy examples — just what broke and what we changed because of it.

If you've hit a version of this — permissions that looked simple until real usage exposed the gaps — I'd like to hear how you solved it.

DEV Community: Chiankem Macbrain