🔐 Roles & Permissions — RawDigs Access Model¶

RawDigs uses Spatie Laravel-Permission (with team support) to handle organization-scoped roles and permissions, combined with custom artist membership policies for creator-level access.

🧭 Overview¶

RawDigs distinguishes between two complementary access domains:

Domain	Managed by	Scope	Description
Organization Access	Spatie Permissions (team-scoped)	per-organization	Controls what members of a label, collective, or company can do
Artist Access	Custom `artist_members` pivot + policies	per-artist	Controls which users can manage a specific artist’s content

Each request executes within an organization context (team scope) set by middleware, while artist access is resolved by checking direct artist membership and fallback organization roles.

🏢 Organization Roles¶

Organizations represent labels, collectives, studios, or companies that own and manage releases, artists, and payouts.

Role	Scope	Description
owner	organization	Full control. Can edit settings, manage payouts, members, and artists.
admin	organization	Manage artists, releases, merch, and invites. Cannot delete org or alter ownership.
manager	organization	Create/edit releases and products, invite artists, view analytics.
artist	organization	Manage own releases and media inside the org.
viewer	organization	Read-only access to dashboards or public stats.

Assigning Roles¶

Roles are assigned per organization via Spatie’s team feature:

$user->assignRole('admin', $organization);

Role Scoping¶

The middleware sets the current organization scope automatically:

app(\Spatie\Permission\PermissionRegistrar::class)
    ->setPermissionsTeamId($organization->id);

This ensures $user->can('release.publish') is evaluated within the correct organization context.

⚙️ Organization Permissions¶

Each organization role aggregates granular permissions:

Permission	Description
`artist.manage`	Manage artists belonging to the organization
`release.create`	Create new releases
`release.edit`	Edit existing releases
`release.publish`	Publish releases
`release.delete`	Delete or archive releases
`product.manage`	Manage physical/digital products
`payout.view`	View financial reports
`payout.configure`	Edit payout and split settings
`member.invite`	Invite or remove members
`member.manage`	Update member roles
`org.settings.update`	Update organization metadata and branding

Default mapping:

Role	Permissions
owner	all permissions
admin	all except `org.settings.update`
manager	`artist.manage`, `release.*`, `product.manage`, `member.invite`
artist	`release.create`, `release.edit`
viewer	none (read-only)

🎤 Artist Access¶

Artists are independent creator entities that may or may not belong to an organization.

Access is controlled via the artist_members pivot table:

Field	Example	Description
`artist_id`	42	The artist entity
`user_id`	5	The user with access
`role`	owner, admin, member, collaborator	Artist-specific role
`permissions`	JSON list	Optional granular overrides (`release.publish`, `payout.view`, etc.)
`status`	active, pending, revoked	Invitation workflow state

Artist Roles¶

Artist Role	Permissions
owner	Full control over artist profile, releases, and splits
admin	Manage content and members, cannot transfer ownership
member	Edit own releases, upload media
collaborator	Temporary or limited permissions for one project

Access Resolution Order¶

When a user acts on an artist, RawDigs checks in this order:

Direct artist membership (artist_members).
Organization membership (if the artist belongs to an org, check org-level permissions such as artist.manage). Label members with this permission can create new artists, automatically linking the artist to the organization and seeding themselves as initial artist admins.
Primary owner bypass (if artist.owner = user).

🧱 Implementation Notes¶

Spatie “team” mode is enabled using organization_id as the team key.
Each organization acts as an isolated permission scope.
Artist access is handled through Laravel policies (ArtistPolicy).
Roles and permissions can be seeded using a dedicated RolesAndPermissionsSeeder.
Middleware like SetPermissionsTeamFromRequest sets the active organization for each request.

Example middleware:

use Spatie\Permission\PermissionRegistrar;

public function handle($request, Closure $next)
{
    $orgId = $request->route('organization')?->id
        ?? $request->user()?->active_organization_id;

    if ($orgId) {
        app(PermissionRegistrar::class)->setPermissionsTeamId($orgId);
    }

    return $next($request);
}

👤 Digger Role¶

Outside of organizations and artists, Digger represents regular users and supporters — listeners, buyers, and followers.

Role	Description
digger	Can browse, follow artists, buy music and merch, leave comments, and build collections.

Diggers have no access to the admin or creator dashboards.

📚 Summary¶

Entity	Role System	Description
Organization	Spatie Permissions (team scoped)	Labels, collectives, or companies managing catalog, payouts, and members
Artist	Custom pivot + Policy	Independent creators managed by users or organizations
User	Participant in one or many orgs/artists	Executes actions based on scoped role and policy
Digger	Public listener/buyer	End-user of the platform

RawDigs’s permission model provides flexible and democratic access control: - Labels manage their rosters. - Artists retain control over their creations. - Supporters enjoy a fair and transparent buying experience.

For authentication surfaces and sequence diagrams, see the Authentication Overview and flow gallery.