Access Control & Permissions

Module Code: PERM Priority: P0 (Critical Foundation - Required for authorization) Status: New (To be developed) Dependencies: User Access & Security

---

Related Documentation

• 🏠 Documentation Home - System overview & all modules

---

Module Overview

Purpose: Comprehensive role-based access control (RBAC) system defining who can do what in the dealership management system.

Priority: P0 (Critical Foundation - Required for authorization)

Dependencies: User Access & Security (M00)

Integration Points: All modules (every module enforces permissions)

---

Functional Specifications

1.1 Role Management

Role Definition:

Attribute	Description	Example
Role ID	Unique identifier	UUID
Role Name	Human-readable name	Sales Manager
Role Code	System code	SALES_MGR
Description	Purpose of role	Manages sales team and approves deals
Department	Associated department	Sales
Level	Hierarchy level	Manager (2)
Is System Role	Protected from deletion	Yes (for Admin)
Active Status	Enable/disable role	Active

System Roles (Pre-defined, cannot be deleted):

Role	Code	Level	Description
System Administrator	SYS_ADMIN	0	Full system access, all permissions
IT Administrator	IT_ADMIN	1	Technical administration, no business data
General Manager	GM	2	Full business operations access
Sales Manager	SALES_MGR	3	Sales department management
Service Manager	SVC_MGR	3	Service department management
Parts Manager	PARTS_MGR	3	Parts department management
Sales Advisor	SALES_ADV	4	Sales consultant, limited permissions
Service Advisor	SVC_ADV	4	Service consultant
Technician	TECH	4	Workshop technician
Parts Specialist	PARTS_SPEC	4	Parts counter staff
Cashier/Accountant	CASHIER	4	Financial transactions
Customer Service	CS_REP	4	Customer care representative
Receptionist	RECEPT	5	Front desk, basic access
Read-Only Auditor	AUDITOR	5	View-only access for compliance

Custom Role Creation:

Step	Action	Validation
1	Define role name and code	Unique code required
2	Assign department	Optional
3	Set hierarchy level	1-10
4	Add description	Required
5	Copy permissions from template	Optional starting point
6	Customize permissions	Module by module
7	Set data scope rules	Own/Department/All
8	Review and save	Admin approval

Role Operations:

Operation	Description	Who Can Do
Create Role	Create new custom role	System Admin only
Edit Role	Modify role details and permissions	System Admin only
Clone Role	Duplicate existing role as template	System Admin only
Activate/Deactivate	Enable or disable role	System Admin only
Delete Role	Remove custom role	System Admin (if not in use)
Assign to User	Give role to user	System Admin, Managers
View Role Details	See role configuration	Admin, IT Admin

1.2 Permission Structure

Permission Hierarchy:

Module Level
    ├── Feature/Section Level
    │       ├── Action Level (CRUD)
    │       │       ├── Create
    │       │       ├── Read/View
    │       │       ├── Update/Edit
    │       │       └── Delete
    │       └── Special Actions
    │               ├── Approve
    │               ├── Export
    │               └── Print
    └── Data Scope
            ├── Own Records Only
            ├── Department Records
            └── All Records

Permission Types:

Type	Level	Example
Module Access	Module	Can access Sales module
Feature Access	Section	Can access Quotations section
CRUD Permissions	Action	Can create quotations
Special Permissions	Action	Can approve discounts
Data Scope	Filter	Can view all quotations vs own only
Field-Level	Granular	Can view price but not edit

Standard Permission Actions:

Action	Code	Description
View/Read	VIEW	Can see records
Create	CREATE	Can create new records
Edit/Update	UPDATE	Can modify existing records
Delete	DELETE	Can remove records
Approve	APPROVE	Can approve pending items
Reject	REJECT	Can reject submissions
Export	EXPORT	Can export data to files
Print	PRINT	Can print documents
Import	IMPORT	Can bulk import data
Assign	ASSIGN	Can assign to other users

1.3 Permission Assignment

Permission Matrix by Module:

Example for M10: Sales Operations

Permission	Sales Advisor	Sales Manager	General Manager
View Quotations	Own only	All	All
Create Quotations	Yes	Yes	Yes
Edit Quotations	Own only	All	All
Delete Quotations	No	Own dept	All
Approve Discounts 0-5%	Yes	Yes	Yes
Approve Discounts 5-10%	No	Yes	Yes
Approve Discounts >10%	No	No	Yes
View Cost Prices	No	Yes	Yes
View All Customers	Department	All	All
Reassign Leads	Own only	Department	All
Export Sales Report	No	Yes	Yes

Data Scope Rules:

Scope	Description	Example
Own	Only records created by or assigned to user	Sales advisor sees only their own customers
Team	Records from user’s team	Team lead sees team members’ data
Department	All records in user’s department	Sales manager sees all sales dept data
Location	Records from user’s branch	Manager sees only their branch
All	All records in system	GM sees all locations, all departments
Custom Filter	Specific criteria-based filter	Only customers in VIP segment

Permission Inheritance:

Rule	Description
Multiple Roles	User inherits permissions from ALL assigned roles (union)
Higher Permission Wins	If one role allows and another denies, allow wins
Data Scope Widest	Widest data scope applies (All > Dept > Own)
Explicit Deny	Explicit deny overrides implicit allow

1.4 Role Assignment to Users

User-Role Relationship:

Attribute	Description
User ID	User account
Role ID	Assigned role
Assigned By	Who assigned the role
Assigned At	When role was assigned
Effective From	When role becomes active
Effective Until	Role expiration (optional)
Is Primary Role	User’s main role (for display)
Assignment Reason	Notes on why role assigned

Assignment Process:

Step	Action
1	Admin/Manager selects user
2	Choose role(s) to assign
3	Set effective date range (optional)
4	Mark primary role
5	Add assignment notes
6	Save and notify user
7	User logs out and back in to activate

Assignment Rules:

Rule	Description
Minimum One Role	Every user must have at least one active role
Primary Role Required	One role must be marked as primary
No Conflicting Roles	Cannot assign conflicting dept roles (Sales + Service Manager)
Manager Approval	Role assignments may require manager approval
Expiry Warning	Alert 7 days before role expires
Auto-Deactivate	Deactivate user if all roles expired

1.5 Approval Workflows

Approval Limits by Role:

Example for Discount Approvals:

Role	Max Discount	Max Deal Value	Requires Higher Approval
Sales Advisor	3%	$50,000	Above limits
Sales Manager	10%	$200,000	Above limits
General Manager	15%	$500,000	Above limits
Owner/CEO	Unlimited	Unlimited	None

Approval Matrix Example:

Action	Requires Approval From	Conditions
Create Quotation	None	-
Apply 5% Discount	Sales Manager	If advisor discount >3%
Apply 10% Discount	General Manager	If any discount >10%
Write-off Bad Debt	CFO + GM	Amount >$10,000
Delete Sales Order	Sales Manager	After deposit received
Refund Customer	Accountant + Manager	Any refund

Approval Workflow:

Step	Action
1	User submits request (e.g., high discount)
2	System checks approval requirements
3	Notification sent to approver
4	Approver reviews request with context
5	Approver approves or rejects with comments
6	Requester notified of decision
7	If approved, action proceeds
8	All steps logged in audit trail

1.6 Permission Checking Engine

Runtime Permission Check:

Step	Check	Result
1	Is user authenticated?	Proceed if yes
2	Is session valid?	Proceed if yes
3	Get user’s roles	Load from cache/DB
4	Get permissions for roles	Union of all role permissions
5	Check module access	Does user have module permission?
6	Check action permission	Does user have action permission?
7	Apply data scope filter	Filter data based on scope
8	Grant or deny access	Return boolean + filtered data

Permission Caching:

Cache Type	Duration	Invalidation
User Permissions	Session lifetime	Role change, logout
Role Definition	1 hour	Role updated
Module Permissions	30 minutes	Permission change

Performance Optimization:

Optimization	Description
Permission Pre-loading	Load all user permissions on login
Cache in Session	Store in session, not DB lookup per request
Lazy Loading	Load module permissions only when accessed
Batch Checks	Check multiple permissions in one call

1.7 Delegation & Temporary Access

Delegation:

Feature	Description
Delegate Authority	User can delegate their permissions to another user temporarily
Delegation Period	Start and end date/time
Partial Delegation	Delegate specific permissions only, not all
Revoke Early	Original user can revoke before end date
Audit Trail	All delegated actions logged with both users

Delegation Process:

Step	Action
1	User initiates delegation
2	Select delegate (another user)
3	Choose permissions to delegate
4	Set time period
5	Add justification
6	Manager approval (if required)
7	Delegate notified
8	Delegated permissions active

Temporary Access:

Use Case	Duration	Approval
Vacation Coverage	1-4 weeks	Manager approval
Project Collaboration	Project duration	Department head approval
Emergency Access	24 hours	Post-approval review
Training/Shadowing	Variable	Manager approval

1.8 Reporting & Analytics

Role Reports:

Report	Description
Role Membership	All users assigned to each role
Permission Matrix	Complete permission grid by role
Orphaned Users	Users with no active roles
Over-Privileged Users	Users with excessive permissions
Role Usage	How often each role is used
Permission Conflicts	Conflicting permission assignments

Audit Reports:

Report	Description
Role Changes	All role modifications over time
Assignment History	Who assigned what role to whom
Access Denied Log	Permission denials and reasons
Delegation Log	All delegation activities
Approval History	Approval requests and outcomes

Compliance Reports:

Report	Purpose
Segregation of Duties	Ensure no user has conflicting roles
Access Certification	Periodic review of user access
Privilege Escalation	Track permission increases
Unused Permissions	Permissions never used (candidates for removal)

---

Data Model

Role Table:

Field	Type	Description
role_id	UUID	Primary key
role_name	VARCHAR(100)	Display name
role_code	VARCHAR(50)	System code (unique)
description	TEXT	Purpose and scope
department	VARCHAR(50)	Associated department
hierarchy_level	INT	Organizational level (0-10)
is_system_role	BOOLEAN	Protected system role
is_active	BOOLEAN	Role enabled/disabled
created_by	UUID	Creator user ID
created_at	TIMESTAMP	Creation time
updated_at	TIMESTAMP	Last update

Permission Table:

Field	Type	Description
permission_id	UUID	Primary key
module_code	VARCHAR(50)	Module identifier (M01, M02, etc.)
feature_code	VARCHAR(50)	Feature/section within module
action_code	VARCHAR(50)	Action (VIEW, CREATE, UPDATE, etc.)
permission_name	VARCHAR(200)	Human-readable name
permission_code	VARCHAR(100)	Unique code
is_dangerous	BOOLEAN	High-risk permission flag
created_at	TIMESTAMP	Creation time

Role-Permission Table:

Field	Type	Description
role_permission_id	UUID	Primary key
role_id	UUID	Foreign key to role
permission_id	UUID	Foreign key to permission
data_scope	ENUM	Own/Team/Dept/Location/All
granted_by	UUID	Who granted permission
granted_at	TIMESTAMP	When granted

User-Role Table:

Field	Type	Description
user_role_id	UUID	Primary key
user_id	UUID	Foreign key to user
role_id	UUID	Foreign key to role
is_primary	BOOLEAN	Primary role flag
assigned_by	UUID	Who assigned
assigned_at	TIMESTAMP	Assignment time
effective_from	TIMESTAMP	Start date
effective_until	TIMESTAMP	End date (optional)
assignment_reason	TEXT	Notes
is_active	BOOLEAN	Currently active

Approval Limits Table:

Field	Type	Description
limit_id	UUID	Primary key
role_id	UUID	Foreign key to role
approval_type	VARCHAR(50)	Discount, Refund, Write-off, etc.
max_amount	DECIMAL	Maximum monetary value
max_percentage	DECIMAL	Maximum percentage
requires_approval_from	UUID[]	Required approver roles
effective_from	TIMESTAMP	Start date
effective_until	TIMESTAMP	End date

Delegation Table:

Field	Type	Description
delegation_id	UUID	Primary key
delegator_user_id	UUID	User delegating
delegate_user_id	UUID	User receiving delegation
permission_ids	UUID[]	Delegated permissions
start_time	TIMESTAMP	Delegation start
end_time	TIMESTAMP	Delegation end
reason	TEXT	Justification
approved_by	UUID	Approver
is_active	BOOLEAN	Currently active
revoked_at	TIMESTAMP	Early revocation

---

Business Rules

Role Management Rules:

Rule	Description
System Roles Protected	Cannot delete or modify critical system roles
Unique Role Codes	Role codes must be unique system-wide
Active Role Deletion	Cannot delete role if assigned to active users
Hierarchy Respect	Lower-level roles cannot have permissions higher-level roles lack

Permission Rules:

Rule	Description
No Orphan Permissions	Every permission must belong to at least one role
Permission Consistency	Create permission should not exist without View
Dangerous Permission Logging	High-risk permissions trigger extra audit logging
Default Deny	Everything denied unless explicitly granted

Assignment Rules:

Rule	Description
Minimum One Role	Users must have at least one active role
Department Consistency	Sales Manager role only for Sales dept employees
Conflict Detection	System warns on conflicting role assignments
Expiry Notification	Alert users 7 days before role expiration

Approval Rules:

Rule	Description
Self-Approval Forbidden	Users cannot approve their own requests
Chain of Approval	Higher authority can override lower approvals
Approval Timeout	Requests pending >7 days escalate to higher level
Emergency Override	GM can override approval process (logged)

---

Integration Points

Outbound Integrations:

Module	Integration Purpose
User Access & Security	Provide permission set for authorization
Employee Directory	Link roles to departments and positions
All Business Modules	Enforce permissions on all operations
M27 Business Intelligence	Permission-based report access

Inbound Integrations:

Module	Integration Purpose
User Access & Security	Receive authentication events
Employee Directory	Auto-assign roles based on job position
Company Configuration	Department-based role filtering

---

User Roles & Permissions

Who Can Manage Roles:

Role	View Roles	Create Roles	Edit Roles	Delete Roles	Assign Roles
System Admin	All	Yes	All	Custom only	All users
IT Admin	All	No	No	No	No
General Manager	All	No	No	No	Department users
Department Manager	Department	No	No	No	Department users

---

Key Performance Indicators

Role Management Metrics:

Metric	Target	Measurement
Roles per User	1-3 average	Avg roles assigned per user
Orphaned Users	0	Users with no active roles
Unused Roles	< 5%	Roles with 0 users
Permission Conflicts	0	Conflicting permission assignments
Access Denials	< 1% of requests	Denied / Total permission checks

Compliance Metrics:

Metric	Target	Measurement
Access Reviews	100% annually	% users reviewed per year
Segregation of Duties	0 violations	Conflicting role combinations
Over-privileged Users	< 5%	Users with excessive permissions
Delegation Compliance	100% approved	% delegations with approval

---

Last Updated: November 14, 2025 Version: 6.0 Migrated From: P0_Baseline_Modules.md