Central RBAC Architecture Documentation #143
Description
Objective
Create central RBAC architecture document serving as single source of truth for understanding the complete RBAC system design.
Scope
File to Create: docs/rbac-architecture.md (in api repository)
Content Overview:
System Architecture
- High-level diagram showing components: Users → Roles → Permissions
- Permission hierarchy: Role Permissions ∪ Direct Permissions
- Temporal constraints layer (optional)
- Database schema overview
Core Concepts
1. Roles
- What are roles?
- Predefined roles (Admin, Manager, Guard, Client, Works Council)
- All roles are equal (no system/custom distinction)
- Role assignment (permanent and temporal)
- Seeder idempotency
2. Permissions
- Permission naming convention:
resource.action - Permission grouping by resource
- Permission assignment to roles
- Permission checking at runtime
3. Direct Permissions
- Definition: Permissions assigned directly to users
- When to use vs roles
- Permission inheritance formula
- Use cases and examples
4. Temporal Assignments
- Definition: Time-limited role/permission assignments
- Optional nature (permanent is default)
- Use cases: vacation coverage, projects, events, compliance
- Automatic expiration handling
- Decision matrix: When to use temporal vs permanent
Design Principles
Document three core decisions (links to ADR-005):
- No System Roles: All roles deletable if not assigned
- Direct Permissions: Bypass roles for exceptional access
- Temporal Optional: Permanent by default, temporal when needed
Implementation Patterns
- How to assign roles (permanent)
- How to assign roles (temporal)
- How to assign direct permissions
- How to check permissions
- How to handle role expiration
API Overview
High-level summary with links to detailed API docs:
- Role Assignment API (4 endpoints)
- Role Management API (7 endpoints) - Phase 4
- Permission Management API (5 endpoints) - Phase 4
- Direct Permission API (4 endpoints) - Phase 4
Developer Guidelines
- When to create new roles vs use direct permissions
- How to choose permanent vs temporal assignments
- Best practices for permission naming
- Testing strategies for authorization
Implementation Checklist
Content Sections
- Overview and introduction
- Architecture diagram (ASCII or Mermaid)
- Permission hierarchy diagram
- Core concepts explained (Roles, Permissions, Direct, Temporal)
- Three design principles with links to ADR-005
- Implementation patterns with code examples
- API overview with links to endpoint docs
- Developer guidelines section
- Links to related documentation
Diagrams
- System architecture (Users → Roles → Permissions)
- Permission hierarchy (Role ∪ Direct)
- Temporal assignment timeline
- Decision tree: When to use what?
Code Examples
- Assign permanent role
- Assign temporal role
- Assign direct permission
- Check permission (with hierarchy)
- Handle expiration
Quality Gates
- REUSE 3.3 compliant (SPDX headers)
- Markdownlint clean
- All internal links work
- Code examples tested
- Diagrams render correctly
Acceptance Criteria
-
docs/rbac-architecture.mdcreated - All four core concepts explained clearly
- Three design principles documented with ADR links
- Permission hierarchy formula shown:
User Permissions = Role Permissions ∪ Direct Permissions - Decision matrix for temporal vs permanent included
- Minimum 5 code examples provided
- Links to API documentation (RBAC API Documentation (Phase 4) #140)
- Links to developer guides (sub-issue #TBD)
- Diagrams illustrate key concepts
- Markdownlint passes
- REUSE compliant
Document Structure Outline
# RBAC Architecture
## Overview
[High-level introduction to RBAC system]
## System Architecture
[Diagram: Users → Roles → Permissions + Direct Permissions]
## Core Concepts
### Roles
[What, Why, How, Predefined roles list]
### Permissions
[Naming convention, Grouping, Assignment]
### Direct Permissions
[Definition, Use cases, Permission hierarchy]
### Temporal Assignments
[Optional nature, Use cases, Expiration handling]
## Design Principles
### 1. No System Roles - All Roles Equal
[Brief explanation, link to ADR-005]
### 2. Direct Permissions Independent of Roles
[Brief explanation, link to ADR-005]
### 3. Temporal Assignments Are Optional
[Brief explanation, link to ADR-005]
## Permission Hierarchy
[Diagram + Formula: User Permissions = Role ∪ Direct]
[Examples showing inheritance]
## Implementation Patterns
### Assigning Permanent Role
[Code example]
### Assigning Temporal Role
[Code example]
### Assigning Direct Permission
[Code example]
### Checking Permissions
[Code example with hierarchy]
### Handling Expiration
[Code example]
## API Overview
[Summary table with links to #140]
## Developer Guidelines
### Decision Trees
- When to create new role vs use direct permission?
- When to use temporal vs permanent assignment?
### Best Practices
- Permission naming conventions
- Role design patterns
- Testing authorization
## References
- ADR-005: RBAC Design Decisions
- Issue #5: RBAC System
- Issue #108: RBAC Phase 4
- docs/guides/direct-permissions.md
- docs/guides/temporal-roles.mdRelated Issues
Part of: #141 - Complete RBAC Documentation Epic
Depends on: #142 - ADR-005 must exist to reference
Blocks: #137-140 - Phase 4 sub-issues need architecture reference
Related:
- 🔐 Implement RBAC System (Role-Based Access Control) #5 - Parent RBAC issue
- RBAC Phase 4: Documentation & Final Testing #108 - RBAC Phase 4
- [EPIC] Migrate Permission System from 'web' to 'sanctum' Guard #125 - Guard Architecture (pattern reference)
Effort Estimate
Time: 1.5-2 hours
Breakdown:
- Structure and overview: 20 min
- Core concepts section: 30 min
- Diagrams: 20 min
- Code examples: 20 min
- Developer guidelines: 15 min
- Review and links: 15 min
Complexity: Medium (comprehensive but well-scoped)
Review Checklist
Before creating PR:
- All core concepts explained clearly
- Three design principles prominently featured
- Permission hierarchy formula correct
- Diagrams accurate and readable
- Code examples tested
- Links to ADR-005 and guides work
- Serves as single entry point for RBAC understanding