RBAC Matrix
This page is the authoritative reference for Role-Based Access Control (RBAC) in Vruksha ERP: the two-layer role model, how org and subproject roles combine, an access matrix of the eight organization roles, the three subproject roles, and the hard stops the system enforces. The behaviour described here is taken from the backend permission guard (permissions.guard.ts) and the roles/permissions configuration.
The two-layer model
Every user has exactly one organization role (their identity across the whole organization) and zero or more subproject roles (each scoped to a single subproject).
- Organization role — defines what the user can do organization-wide. Examples: Admin, Finance Manager, Sales Head.
- Subproject role — adds scoped permissions for a specific subproject. A user can hold different subproject roles in different subprojects, but only one role per subproject.
ORG ROLE (exactly one) ──► organization-wide baseline permissions
SUBPROJECT ROLES (0..n) ──► extra permissions, each scoped to one subproject
The override / merge rule
How effective permissions are resolved depends on whether the request targets a specific subproject. This is exactly what the permission guard implements:
| Scenario | Effective permissions |
|---|---|
| User has no subproject roles | Organization role permissions only. |
Request targets a specific subproject (URL carries a subprojectId) and the user has a subproject role for that subproject | Organization permissions + that subproject's role permissions, merged (union). |
| Request targets a specific subproject for which the user has no subproject role | Organization role permissions only. |
Request has no subproject context (e.g. POST /quotations, /leads) and the user has subproject roles | Organization permissions + the permissions of ALL the user's subproject roles, merged (union). |
Key properties:
- Subproject roles always ADD permissions on top of the org role for their scope. They never strip away org-role permissions.
- Permission checks use OR logic: a request that requires one of several permissions succeeds if the user's effective set contains at least one of them.
- The org role is always the baseline / fallback. When no subproject role applies, only the org role is used.
- Subproject roles only take effect inside their assigned subproject — they cannot "leak" to other subprojects.
Note on terminology. Some internal design notes describe subproject roles as "completely overriding" the org role. The shipping permission guard implements a merge (union): org permissions are the baseline and the applicable subproject role's permissions are added on top. The net effect for scoped actions is that the subproject role governs what extra a user can do in that subproject, while the org role remains the floor. The matrices below describe the resulting access.
Organization roles (8)
| Role | Scope | Summary |
|---|---|---|
| Admin | Full system | All operations, user/role management, approvals, settings, audit. |
| Partner | Partnership-scoped | View own partnership data and statements. |
| Self-Managed Partner | Extended partner | Manage own profile(s); view own investments. |
| Finance Manager | Financial operations | Payments, reconciliation, financial reports, bank accounts. |
| Sales Head | Sales management | Quotations, Sales Order approvals, pricing overrides, sales reports. |
| Sales Staff | Limited sales | Create quotations and SO drafts (no approve/cancel/override). |
| Project Manager | Project operations | Units, SVG layouts, documents across projects. |
| People Manager (HR) | HR operations | Employee management, user lifecycle (HR scope). |
Org-role access matrix (summary)
Legend: F = full (view/create/edit/delete/approve), C = create/edit, V = view only, A = approve, – = no access. This is a high-level summary; the authoritative grant is the per-permission configuration in the backend.
| Module | Admin | Partner | Self-Mgd Partner | Finance Mgr | Sales Head | Sales Staff | Project Mgr | People Mgr (HR) |
|---|---|---|---|---|---|---|---|---|
| Users & Roles | F | – | – | – | – | – | – | C |
| Settings / Masters | F | – | – | V | – | – | – | – |
| Parties | F | V | V | V | C | C | V | – |
| Partners | F | V | C* | V | – | – | – | – |
| Partnerships | F | V | V | V | – | – | – | – |
| Projects / Subprojects | F | V | V | V | V | V | C | – |
| Stock Management | F | V | V | V | – | – | V | – |
| Quotations | F | – | – | V | F | C | – | – |
| Sales Orders | F | – | – | V | C + A | C | – | – |
| Sales Invoices | F | – | – | C + A | C | V | – | – |
| Bank Accounts | F | V | V | F | – | – | – | – |
| Documents | F | V | V | V | C | C | C | – |
| Reports | F | V (own) | V (own) | F | V | V | V | V (HR) |
| Audit & Logs | F | – | – | V | – | – | – | – |
* Self-Managed Partner manages their own partner profile only.
This matrix is a navigational summary. The system enforces access at the individual-permission level (e.g.
sales_orders.approve,quotations.override_pricing), not at the module level. Where a cell shows "C + A", approval is a distinct permission held by that role.
Subproject roles (3)
Subproject roles are intentionally scoped and draft-oriented: they let people operate inside a specific subproject without granting organization-wide authority such as approval, cancellation, override, or finance access.
Sales Head (subproject)
- Lead management for the subproject; create/edit quotations and SO drafts.
- View sales orders and refunds (read-only) to coordinate the pipeline.
- Cannot approve, cancel, or override — those remain org-level.
Sales Staff (subproject)
- Create/edit leads assigned to them and quotation drafts; upload documents.
- Cannot reassign leads, approve, or convert beyond draft level.
Project Manager (subproject)
- Unit management and SVG operations within the subproject; upload documents.
- Read-only visibility into sales orders/refunds to flag conflicts.
- Cannot publish layouts, split/merge/switch units, or perform structural changes — those are org-level (Admin).
Hard stops & security boundaries
Regardless of how many subproject roles a user holds, the following actions are never available through a subproject role — they require an organization-level role (typically Admin):
| Action | Why it is reserved |
|---|---|
| Approve anything (SO, SI, quotations, refunds) | Approval authority is org-level. |
| Cancel anything (SO, SI, stocks) | Cancellation requires org-level authority. |
| Modify ownership (partner holdings, unit shareholders) | Structural ownership changes are Admin-only. |
| Access bank accounts / financial periods | Finance is org-level only. |
| Publish SVG layouts | Customer-facing publishing is Admin-only. |
| Split / merge / switch units | Structural operations are Admin-only. |
| Override pricing or validations | Override authority is Admin-only. |
| Manage users or roles | User management is Admin/HR only. |
| Access audit logs | Audit visibility is Admin-only. |
| Manage master data / settings | Settings are Admin-only. |
| Access partnerships directly | Partnerships are org-level, not subproject-scoped. |
Security invariants
| Invariant | Description |
|---|---|
| Subproject isolation | A subproject role applies only within its assigned subproject; it cannot affect other subprojects. |
| No implicit elevation | Holding a subproject role never grants more than that role explicitly contains. |
| Admin immunity | The Admin org role always has full access; subproject roles do not constrain Admin. |
| Fail-closed | If a permission is not explicitly granted, it is denied. |
| Server-side enforcement | The backend permission guard is the source of truth; the frontend only hides/shows UI for convenience. |
| Fresh load per request | Subproject role permissions are resolved on every request — no stale data. |
| One role per subproject | A user cannot hold two different roles for the same subproject. |
Worked examples
| Situation | Effective permissions | Outcome |
|---|---|---|
| Sales Staff (org) with subproject Sales Head role in Sunrise Layout, editing a quotation in Sunrise Layout | Org (Sales Staff) + subproject Sales Head perms for Sunrise Layout | Allowed (create/edit quotation draft). |
| Same user tries to approve a Sales Order in Sunrise Layout | Neither org nor subproject role grants sales_orders.approve | 403 Forbidden — approval is a hard stop. |
| Project Manager (org) opening a unit in a subproject where they hold no subproject role | Org role only | Org Project Manager access applies. |
Any user calling POST /quotations (no subproject in URL) while holding subproject roles | Org + union of all their subproject roles | Allowed if the union contains the required permission. |
Sensitive-data permissions (PII/PCI)
Beyond the module permissions above, Vruksha ERP masks personal and financial data (PAN, Aadhaar, GSTIN, bank details, contact info, addresses, sensitive uploads) by default and only reveals it to people who hold a dedicated sensitive-data permission. There are nine such permissions, and every reveal or sensitive-file download is audited. For the full behaviour — masking formats, the reveal flow, and the five file-sensitivity tiers — see Data Security (PII & PCI).
What each permission unlocks
| Permission | Unlocks |
|---|---|
| Parties — view sensitive | Reveal masked party PII (PAN, Aadhaar, GSTIN, email, mobile, address). |
| Partners — view sensitive | Reveal masked partner PII. |
| Bank accounts — view sensitive | Reveal masked account number and IFSC. |
| Users — view sensitive | Reveal masked user email, phone, and address. |
| Leads — view sensitive | Reveal masked lead phone, email, and address. |
| Custom fields — view sensitive | Reveal values of custom fields marked "sensitive". |
| Documents — download sensitive | Download/preview files at SENSITIVE level and above. |
| Files — view PCI | Additionally required to access PCI-DSS files. |
| Files — view confidential | Additionally required to access CONFIDENTIAL files. |
Default grants by org role
Legend: ✓ = granted, – = not granted.
| Permission | Admin | Finance Mgr | All other roles* |
|---|---|---|---|
| Parties — view sensitive | ✓ | – | – |
| Partners — view sensitive | ✓ | – | – |
| Bank accounts — view sensitive | ✓ | ✓ | – |
| Users — view sensitive | ✓ | – | – |
| Leads — view sensitive | ✓ | – | – |
| Custom fields — view sensitive | ✓ | ✓ | – |
| Documents — download sensitive | ✓ | ✓ | – |
| Files — view PCI | ✓ | ✓ | – |
| Files — view confidential | ✓ | – | – |
* "All other roles" = Partner, Self-Managed Partner, Sales Head, Sales Staff, Project Manager, and People Manager (HR). These roles receive none of the sensitive-data permissions and see masked values only.
Admin holds all nine. Finance Manager holds exactly four — Bank accounts — view sensitive, Custom fields — view sensitive, Documents — download sensitive, and Files — view PCI — and notably does not get party/partner/user/lead reveal or Files — view confidential.
Related: Data Security (PII & PCI) for masking and reveal behaviour, Auth Flows for how users authenticate, and Validation Rules for organization-level data isolation that underpins all RBAC checks.