ADR-005: Document RBAC Core Design Decisions

[kevalyq]

Objective

Create ADR-005 documenting three critical RBAC design decisions that are currently only described in issue threads.

Scope

File to Create: adrs/005-rbac-design-decisions.md (in .github repository)

Design Decisions to Document:

1. No System Roles - All Roles Equal

Current State: Documented only in Issue #108 under "Design Decisions" section

Decision: No is_system_role flag. All roles (Admin, Manager, Guard, Client, Works Council, Custom) are equal and fully manageable.

Key Points:

• Simple deletion rule: Can only delete if NOT assigned to users
• Seeder is idempotent (uses firstOrCreate)
• Deleted predefined roles are recreated on next seeder run
• No artificial distinction between "system" and "custom" roles
• All roles can be renamed, permissions changed, and deleted (if not assigned)

Rationale:

• Simplicity: One rule for all roles
• Flexibility: Everything manageable via UI/API
• No confusion: No need to explain "system vs custom" to users
• Protection through assignment status, not flags

2. Direct Permissions - Independent of Roles

Current State: Documented only in Issue #138 and partially in #108

Decision: Users can have permissions assigned directly, bypassing roles entirely.

Permission Hierarchy: User Permissions = Role Permissions ∪ Direct Permissions

Key Points:

• Direct permissions work independently of role assignments
• If role removed, direct permissions remain
• Use cases: Temporary special access, exceptions, overrides
• Avoids creating single-use roles

Rationale:

• Flexibility for edge cases
• Reduces role proliferation
• Supports temporary exceptions without role management overhead
• Clear separation: Roles for standard access patterns, Direct for exceptions

3. Temporal Assignments Are Optional

Current State: Implied by nullable columns, never explicitly stated as principle

Decision: Role and permission assignments are PERMANENT by default. Temporal constraints (valid_from, valid_until) are OPTIONAL.

Key Points:

• Default behavior: Permanent assignments (no expiration)
• Temporal use cases: Vacation coverage, projects, events, compliance testing
• Both roles AND direct permissions support temporal constraints
• Use temporal ONLY when time-limited access is required

Rationale:

• Permanent is the common case (80%+ of assignments)
• Temporal adds complexity (expiration tracking, notifications)
• Explicitly optional prevents over-engineering
• Matches real-world usage patterns

Implementation Checklist

ADR Structure

• Use standard ADR format (Status, Context, Decision, Consequences)
• Document all three decisions in one ADR (related architectural choices)
• Include code examples for each decision
• Link to relevant issues (🔐 Implement RBAC System (Role-Based Access Control) #5, RBAC Phase 4: Documentation & Final Testing #108, Permission Management CRUD API (RBAC Phase 4) #137-140)
• Status: Accepted (decisions already implemented in Phases 1-3)

Content Requirements

• Context: Why these decisions were needed
• Decision: Clear statement of each choice
• Consequences: Positive and negative impacts
• Examples: Code snippets showing implementation
• Alternatives Considered: Why other approaches were rejected

Quality Gates

• REUSE 3.3 compliant (SPDX headers)
• Markdownlint clean
• Links to issues work
• Consistent with ADR-004 format

Acceptance Criteria

• ADR-005 created in .github/adrs/ directory
• All three design decisions documented with full context
• Each decision includes rationale and consequences
• Code examples provided for implementation patterns
• Links to related issues (🔐 Implement RBAC System (Role-Based Access Control) #5, RBAC Phase 4: Documentation & Final Testing #108, Permission Management CRUD API (RBAC Phase 4) #137-140)
• Referenced in .github/README.md ADR index
• Markdownlint passes
• REUSE compliant

ADR Template Outline

# ADR-005: RBAC Design Decisions

**Status:** Accepted  
**Date:** 2025-11-09  
**Deciders:** SecPal Core Team  

## Context

RBAC system (Issue #5) required architectural decisions about role mutability, permission assignment patterns, and temporal constraints...

## Decisions

### Decision 1: No System Roles - All Roles Equal

[Context, decision statement, rationale]

### Decision 2: Direct Permissions Independent of Roles

[Context, decision statement, rationale]

### Decision 3: Temporal Assignments Are Optional

[Context, decision statement, rationale]

## Consequences

### Positive
- [Benefits of these approaches]

### Negative
- [Trade-offs and limitations]

## Implementation Notes

[Code examples, database schema, API patterns]

## References
- Issue #5: RBAC System
- Issue #108: RBAC Phase 4
- ADR-004: RBAC Architecture (Spatie vs Custom)

Related Issues

Part of: #141 - Complete RBAC Documentation Epic
Builds on:

• 🔐 Implement RBAC System (Role-Based Access Control) #5 - Parent RBAC issue
• RBAC Phase 4: Documentation & Final Testing #108 - Contains original design rationale
• ADR-004 - RBAC architecture foundation

Blocks:

• Sub-issues for architecture docs and guides (depend on formal decisions)

Effort Estimate

Time: 45-60 minutes
Breakdown:

• Structure and context: 15 min
• Document three decisions: 25 min
• Examples and consequences: 15 min
• Review and links: 5 min

Complexity: Low (design decisions already made, just formalizing)

Review Checklist

Before creating PR:

• All three decisions clearly stated
• Rationale explains "why" not just "what"
• Consequences include trade-offs
• Code examples tested and accurate
• Links to issues work
• Consistent with ADR-004 format
• SPDX headers present

[github-actions]

✅ This issue has been added to the SecPal Feature Roadmap with status: 💡 Ideas

New idea - needs discussion and evaluation

Status Flow:
💡 Ideas → 💬 Discussion → 📥 Backlog → 📋 Planned → 🚧 In Progress → 👀 In Review → ✅ Done

Note: Ideas that won't be implemented should be moved to 🚫 Won't Do with a reason.