System Blueprint → Access engine (permissions)

Permissions and Delegation Design Specification

This page defines the permission and delegation model only.

it is not an implementation page
it is not a route/API page
it is not a current-state audit
it explains how permissions should be designed regardless of current service status

It describes the intended logic for:

company commercial eligibility
user permissions
scope restrictions
delegation

1. Permission model layers

The platform should resolve access in layers:

Layer 1: company commercial eligibility

Question:

Did the company buy the relevant package, module, or add-on?

Layer 2: user module access

Question:

Is the user allowed to access that module?

Layer 3: user permission access

Question:

What actions inside that module are allowed?

Layer 4: scope restrictions

Question:

Is the user limited to a company, business unit, workflow slice, or data subset?

Layer 5: delegation

Question:

What can this user grant or manage for someone else?

This layered model must always be preserved. One layer must not silently replace another.

2. Permission naming rules

Permissions should always be namespaced by module.

Examples:

basic.artists.read
basic.events.create
basic.tasks.manage
finance.expenses.read
finance.income.read
finance.bills.read
market.contracts.read
ai.predictions.read
venue.availability.read

Each permission should be structured like:

<module>.<resource>.<action>

Where:

module = product boundary
resource = business object or feature area
action = read, create, update, approve, manage, export, etc.

2.1 Permission design rules

Permission names must:

remain stable
be meaningful to backend and frontend teams
reflect business capability, not UI component names
never include package names
never include temporary pricing or campaign language

Good examples:

finance.reports.read
basic.contacts.read
market.contracts.write

Bad examples:

basic-package-user
promo-finance-editor
screen-4-edit

3. Permission families by module

3.1 Basic

Examples:

basic.artists.read
basic.artists.analyze
basic.contacts.read
basic.events.read
basic.events.create
basic.events.update
basic.market-study.read
basic.pnl.read
basic.tasks.manage
basic.news.read

3.2 Finance

Examples:

finance.expenses.read
finance.expenses.write
finance.income.read
finance.income.write
finance.bills.read
finance.bills.write
finance.ticketing.read
finance.reports.read
finance.vendors.read

3.3 AI

Examples:

ai.predictions.read
ai.research.read
ai.valuations.read
ai.sales-reports.read

3.4 Touring

Examples:

touring.routes.read
touring.routes.write
touring.logistics.manage
touring.coordination.manage

3.5 Market

Examples:

market.contracts.read
market.contracts.write
market.escrow.read
market.investments.read

3.6 Venue Availability

Examples:

venue.availability.read
venue.details.read
venue.details.write
venue.calendar.read
venue.calendar.write
venue.bookings.read
venue.bookings.write
venue.customers.read
venue.customers.write
venue.contracts.read
venue.contracts.write
venue.deposits.read
venue.deposits.write
venue.approvals.read
venue.approvals.approve
venue.reports.read
venue.operations.manage

4. Actions and permission semantics

The action segment should be consistent across the platform.

Common actions:

read
create
update
delete
approve
manage
export
assign

4.1 Action meaning

Use actions consistently:

read = can view
create = can create new records
update = can modify existing records
delete = can remove or archive records
approve = can perform controlled approval workflows
manage = broad administrative control over a resource family
export = can export/report/download structured output
assign = can link or grant access to something

5. Scope restrictions

Permissions alone are not always enough.

Some access must also be scoped.

Examples:

a user can read bills but only for one business unit
a user can read finance reports but not income details
a user can update events only inside one operational scope

Possible scope models:

company scope
business-unit scope
workflow scope
ownership scope

Example:

User has:
- finance.bills.read

Scope:
- business unit = BU-X only

Result:
- user can read bills
- but only for BU-X

5.1 Important scope rule

Scope should narrow a permission.
Scope should not create a permission that does not otherwise exist.

Bad design:

No finance permission exists
but BU scope alone gives finance access

Good design:

finance.bills.read exists
scope narrows it to BU-X

6. Delegation

Delegation must be documented as a separate concept from permission.

6.1 Permission

Permission means:

What can this user do personally?

6.2 Delegation

Delegation means:

What can this user grant or manage for someone else?

6.3 Example

A manager may have:

finance.bills.read
finance.bills.write

But delegation may allow them to grant only:

finance.bills.read

and not:

finance.bills.write
finance.income.read

So a user may personally have more access than they are allowed to delegate.

7. Delegation fields

Delegation should conceptually control:

grantable modules
grantable permissions
whether the user can manage users
whether the user can buy or assign add-ons
whether the user can assign access across all business units or only some scopes

Examples:

ADMIN
- can grant: basic, finance
- can grant permissions: finance.bills.read, finance.expenses.read
- canManageUsers: true
- canBuyAddons: false

MANAGER
- can grant: basic
- can grant permissions: basic.events.read, basic.tasks.manage
- canManageUsers: false
- canBuyAddons: false

7.1 Delegation must never exceed personal access

A user must never be able to grant:

a module they do not personally control in an allowed way
a permission they are not allowed to delegate
a scope broader than their own governance authority

8. Relationship to packages, modules, and add-ons

Permissions are not designed directly from package names.

Use this order:

Package / standalone module / add-on
-> commercial eligibility
-> module eligibility
-> permission-family eligibility
-> user permission grants
-> scope restrictions
-> delegation limits

8.1 Package

Package determines what is commercially available.

8.2 Module

Module determines the permission namespace.

8.3 Add-on

Add-on may unlock additional capability eligibility.

8.4 Permission

Permission determines what the user can do.

8.5 Delegation

Delegation determines what the user may grant or manage for someone else.

9. Finance examples

9.1 Bills only

Company owns finance module
User gets:
- finance.bills.read
User does not get:
- finance.income.read

Result:

user can access bills
user cannot access income

9.2 Bills for one business unit only

Company owns finance module
User gets:
- finance.bills.read
Scope:
- BU-X only

Result:

user can access bills
only inside BU-X

9.3 Delegation example

Manager has:
- finance.bills.read
- finance.bills.write

Delegation:
- may grant finance.bills.read only

Result:

manager can use write access personally
manager cannot grant write access to other users

10. Summary

The access model must stay clean:

packages, modules, and add-ons decide commercial eligibility
permissions decide user actions
scope decides where those actions apply
delegation decides what can be granted to others

These concerns must stay separate or the access model will become inconsistent very quickly.