Role-Based Security & Workflow Permissions — business view

1. Business Summary

A configurable engine that decides — for every record of every entity — which users may view, create, update, or delete it, based on the record's current status, the role/actor field on the record, and traversed relationships across the data graph (e.g., "the manager of the assignee of this task can approve it"). Permissions are pre-computed for performance and rebuilt in the background whenever an entity changes.

2. Business Value

Lets confidentiality and accountability be enforced consistently across complex workflows (PMs, AMs, VMs, finance, vendors) without per-screen custom code.

3. Users / Stakeholders

Every user is implicitly affected; security configuration is maintained by administrators.

4. Workflows

• Configure an entity for security. Mark the entity as "secured", define its workflow statuses with priority and conditions, define events (create/update/delete), link events to statuses, and link those to roles, actor fields, and relationship paths.
• Real-time access check. When a user opens a record, the system looks up pre-computed grants to decide what is visible/editable.
• Privilege rebuild on change. When a record is created/updated/deleted, an entry is queued; a background job re-evaluates the new status, recomputes grants, and updates pre-computed tables. The job cascades to related records when needed (e.g., a parent change can update children).

5. Sub-Features

• Privilege templates, status conditions, event/role/actor mappings.
• Path-based traversal flows (descendant, reverse, root, all-users-of-brand).
• Background queue with retry.
• "Substitute" attribution in audit (basic-user vs. on-behalf-user).
• Hard-coded blacklist for very heavy records that exceed processing thresholds.

6. Business Rules

• Only entities flagged "secured" enforce row-level security.
• Statuses are priority-ordered: the first matching status wins.
• Administrators bypass the engine.
• Some heavy records (e.g., specific large price books) are deliberately skipped to protect performance.

7. Data Entities

• Entity, EntityStatus, EntityStatusDetail, EntityActorField, Event, EventEntityStatus, EventPrivilegeRole.
• Privilege Templates and Details.
• Pre-computed Security{Entity} and Security{Entity}User tables (one pair per secured entity).
• Background queue (cron job queue) and retry log.

8. Entry Points

• Admin-side security engine UI (events, statuses, templates, actors).
• Background privilege rebuild jobs.

9. Inputs & Outputs

• Inputs: entity changes, configuration, queue messages.
• Outputs: pre-computed grants, audit logs, queue completions.

10. Integrations

• AWS SQS for asynchronous dispatch.

11. Calculations / Logic

• Path traversal evaluates relationship strings dynamically.

12. Status Lifecycle

• Per record: status flows according to configuration; transitions trigger re-evaluation.

13. Permissions

• Configuration restricted to administrators.

14. Reports & KPIs

• Background queue depth, error counts, retry counts.

15. Risks & Observations

• Hard-coded blacklist of heavy items signals an unresolved performance debt.
• The audit field used for substitution is not validated, allowing misattribution risk.
• Security can be silently disabled by toggling an entity's "secured" flag.
• Path traversal uses arbitrary string paths rather than a whitelist.
• A dedicated administrator persona is required to keep the configuration coherent.

16. Source Code Evidence

• app/Plugin/Security/*, app/Controller/SecurityCronJobsController.php, app/Controller/Component/SecuritySystemComponent.php, app/Model/Behavior/SecuritySystemBehavior.php.