README Update & Phase 4 Sub-Issue References

[kevalyq]

Objective

Make RBAC documentation discoverable by adding README section and ensuring Phase 4 sub-issues reference design decisions.

Scope

Files to Modify:

1. README.md - Add RBAC System section
2. Issue Permission Management CRUD API (RBAC Phase 4) #137 - Add design decision reference
3. Issue User Direct Permission Assignment API (RBAC Phase 4) #138 - Add design decision reference
4. Issue Predefined Roles \u0026 Permissions Seeder (Idempotent) - RBAC Phase 4 #139 - Add design decision reference
5. Issue RBAC API Documentation (Phase 4) #140 - Add design decision reference

Task 1: README.md RBAC Section

Location

Add new section after "Authentication" section (around line 80-100)

Content Structure

Section Title

## RBAC System

SecPal implements a comprehensive Role-Based Access Control (RBAC) system with temporal role assignments and direct permission management.

Core Features (3-5 sentences)

• Role-based access control with predefined roles (Admin, Manager, Guard, Client, Works Council)
• Temporal role assignments with automatic expiration for time-limited access
• Direct permissions allowing exceptions without creating new roles
• All roles are equal and fully manageable (no system/custom distinction)
• Idempotent seeder recreates deleted predefined roles

Three Core Concepts

1. No System Roles
Brief explanation (2-3 sentences) with link to ADR-005

2. Direct Permissions
Brief explanation (2-3 sentences) with link to guides

3. Temporal Assignments
Brief explanation (2-3 sentences) with link to guides

Quick Examples

Assign Permanent Role:

POST /api/v1/users/{id}/roles
{"role": "manager"}

Assign Temporal Role:

POST /api/v1/users/{id}/roles
{
  "role": "manager",
  "valid_until": "2025-12-14T23:59:59Z"
}

Assign Direct Permission:

POST /api/v1/users/{id}/permissions
{"permissions": ["employees.export"]}

Documentation Links

• Architecture Overview: docs/rbac-architecture.md
• Direct Permissions Guide: docs/guides/direct-permissions.md
• Temporal Roles Guide: docs/guides/temporal-roles.md
• ADR-005: RBAC Design Decisions
• API Documentation: Issue RBAC API Documentation (Phase 4) #140

Implementation Checklist

• Add RBAC section after Authentication
• Document three core concepts
• Include 3 quick examples
• Add links to all related documentation
• Keep concise (target: 20-30 lines total)
• Markdownlint clean
• Links work

Task 2: Update Issue #137 (Permission Management CRUD API)

Changes to Make

Add new section at the top (after Objective, before Scope):

## 🎯 Design Context

**Important Design Decisions:**
- **No System Roles**: All roles are equal and deletable if not assigned to users. See [ADR-005](link) and [Issue #108](link) for rationale.
- **Seeder Idempotency**: Deleted predefined roles are recreated on next seeder run.

**Architecture Reference:**
See `docs/rbac-architecture.md` for complete RBAC system overview.

Purpose

Ensure implementer knows:

• Permissions are not tied to "system roles" concept
• Deletion rules apply equally to all roles
• Architecture document exists for reference

Task 3: Update Issue #138 (User Direct Permission Assignment API)

Changes to Make

Add new section at the top:

## 🎯 Design Context

**Important Design Decisions:**
- **Direct Permissions**: Users can have permissions independent of roles. See [ADR-005](link) for rationale.
- **Permission Hierarchy**: `User Permissions = Role Permissions ∪ Direct Permissions`
- **Temporal Optional**: Direct permissions can be permanent OR time-limited (not mandatory).

**Architecture Reference:**
- Central docs: `docs/rbac-architecture.md`
- Detailed guide: `docs/guides/direct-permissions.md`

Purpose

Ensure implementer understands:

• Direct permissions are a core feature, not an edge case
• Temporal constraints are optional
• Permission inheritance works correctly

Task 4: Update Issue #139 (Predefined Roles & Permissions Seeder)

Changes to Make

Add new section at the top:

## 🎯 Design Context

**Important Design Decisions:**
- **No System Roles**: Predefined roles (Admin, Manager, Guard, Client, Works Council) are NOT protected at runtime. See [ADR-005](link).
- **All Roles Equal**: Predefined roles can be deleted if not assigned to users.
- **Idempotent Seeder**: Uses `firstOrCreate()` - deleted roles are recreated on next run.

**Why This Approach:**
Simplicity, flexibility, no artificial distinction between "system" and "custom" roles. Protection through assignment status, not flags.

**Architecture Reference:**
See `docs/rbac-architecture.md` for complete rationale.

Purpose

Critical clarification:

• No is_system_role flag to implement
• Seeder just creates roles, doesn't protect them
• Design decision is intentional, not missing feature

Task 5: Update Issue #140 (RBAC API Documentation)

Changes to Make

Update "Related Issues" section to add:

**Architecture Documentation:**
- `docs/rbac-architecture.md` - Central RBAC overview
- `docs/guides/direct-permissions.md` - Direct permission patterns
- `docs/guides/temporal-roles.md` - Temporal assignment patterns
- ADR-005 - Core design decisions

Purpose

API documentation should reference architecture docs for context.

Implementation Checklist

README.md Update

• Add RBAC section after Authentication
• Document three core concepts briefly
• Include 3 quick API examples
• Add links to all documentation
• Markdownlint clean

Issue #137 Update

• Add design context section
• Link to ADR-005
• Reference architecture doc

Issue #138 Update

• Add design context section
• Explain permission hierarchy
• Clarify temporal optional
• Link to guides

Issue #139 Update

• Add design context section
• Clarify no is_system_role flag
• Explain idempotency
• Link to ADR-005

Issue #140 Update

• Add architecture doc references
• Link to guides

Quality Gates

• All links work (ADR, docs, issues)
• Consistent messaging across all updates
• No redundancy (each issue gets relevant context only)
• Markdownlint clean for README

Acceptance Criteria

• README.md contains RBAC section with three core concepts
• README includes links to all RBAC documentation
• Issue Permission Management CRUD API (RBAC Phase 4) #137 references "No System Roles" decision
• Issue User Direct Permission Assignment API (RBAC Phase 4) #138 references "Direct Permissions" concept and guides
• Issue Predefined Roles \u0026 Permissions Seeder (Idempotent) - RBAC Phase 4 #139 clarifies no is_system_role flag with rationale
• Issue RBAC API Documentation (Phase 4) #140 links to architecture documentation
• All internal links verified and working
• Consistent terminology across all updates
• Markdownlint passes for README

Related Issues

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

• ADR-005: Document RBAC Core Design Decisions #142 - ADR-005 must exist to link
• Central RBAC Architecture Documentation #143 - Architecture doc must exist to link
• Developer Guides: Direct Permissions & Temporal Roles #144 - Guides must exist to link

Updates:

• Permission Management CRUD API (RBAC Phase 4) #137 - Permission Management CRUD API
• User Direct Permission Assignment API (RBAC Phase 4) #138 - User Direct Permission Assignment API
• Predefined Roles \u0026 Permissions Seeder (Idempotent) - RBAC Phase 4 #139 - Predefined Roles & Permissions Seeder
• RBAC API Documentation (Phase 4) #140 - RBAC API Documentation

Related:

• 🔐 Implement RBAC System (Role-Based Access Control) #5 - Parent RBAC issue
• RBAC Phase 4: Documentation & Final Testing #108 - RBAC Phase 4 parent

Effort Estimate

Time: 45-60 minutes
Breakdown:

• README RBAC section: 20 min
• Issue Permission Management CRUD API (RBAC Phase 4) #137 update: 5 min
• Issue User Direct Permission Assignment API (RBAC Phase 4) #138 update: 5 min
• Issue Predefined Roles \u0026 Permissions Seeder (Idempotent) - RBAC Phase 4 #139 update: 10 min (most critical clarification)
• Issue RBAC API Documentation (Phase 4) #140 update: 5 min
• Link verification: 5 min

Complexity: Low (mostly adding references)

Review Checklist

Before creating PR / updating issues:

• README RBAC section comprehensive but concise
• Three core concepts clearly stated
• All links to documentation work
• Issue updates provide context without redundancy
• Issue Predefined Roles \u0026 Permissions Seeder (Idempotent) - RBAC Phase 4 #139 clearly states no is_system_role flag
• Consistent messaging across all locations
• No copy-paste from issues (original wording)

[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.