Document Guard Architecture and sanctum usage

[kevalyq]

🎯 Objective

Document the Laravel Guard architecture and explain why SecPal uses 'sanctum' guard for all permissions.

📋 Changes Required

New Documentation File

Create: docs/GUARD_ARCHITECTURE.md

Content Structure

1. Laravel Guards Overview

   • What is a guard?
   • Common guard types (web, sanctum, api)
   • How guards relate to authentication

2. SecPal Architecture Decision

   • Frontend: React PWA with Bearer tokens
   • Backend: Token-based API (stateless)
   • No session/cookie usage
   • Therefore: 'sanctum' guard throughout

3. Spatie Permission Integration

   • Permissions are guard-aware
   • Why guard_name='sanctum' is required
   • What happens if guard mismatch occurs

4. Migration Context

   • Historical: Permissions defaulted to 'web'
   • Problem: Semantic mismatch with actual auth mechanism
   • Solution: EPIC [EPIC] Migrate Permission System from 'web' to 'sanctum' Guard #125 systematic migration

5. Developer Guidelines

   • Always specify guard_name='sanctum' when creating permissions
   • User model has $guard_name = 'sanctum'
   • All routes use auth:sanctum middleware

Example Code Snippets

// ✅ Correct: Permission for sanctum guard
Permission::create([
    'name' => 'employees.read',
    'guard_name' => 'sanctum',
]);

// ❌ Wrong: Defaults to 'web' guard
Permission::create(['name' => 'employees.read']);

✅ Acceptance Criteria

• New file: docs/GUARD_ARCHITECTURE.md
• Explains guard concept clearly
• Documents SecPal's architecture decision
• Includes code examples (correct & incorrect)
• References EPIC [EPIC] Migrate Permission System from 'web' to 'sanctum' Guard #125 for context
• REUSE compliant (SPDX headers)
• Markdown linting passes

📊 Expected Impact

Before: Implicit knowledge, confusion about guard usage
After: Clear documentation, onboarding resource for new developers

🔗 Related

• Parent: [EPIC] Migrate Permission System from 'web' to 'sanctum' Guard #125 (EPIC: Migrate Permission System to sanctum guard)
• Depends on: None (documentation is independent)
• Can be done: In parallel with code changes

⏱️ Effort Estimate

Time: 30-45 minutes
Complexity: Medium (requires clear technical writing)

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