castle/docs/UI-IMPROVEMENTS-PLAN.md
padreug cbdd5f3779 Add UI improvements plan for bulk permission features
Documents comprehensive enhancements to Castle permissions UI:
- Analytics dashboard with permission usage statistics
- Bulk grant operations for multiple users
- Permission template copying from experienced users
- User offboarding with revoke-all
- Account sync UI with manual trigger
- Expiring permissions alerts

Implementation prioritized into 3 phases:
- Phase 1 (2-3 days): Analytics, bulk grant, account sync
- Phase 2 (2-3 days): Copy permissions, offboard, alerts
- Phase 3 (later): Templates, advanced analytics

Showcases backend features from account_sync.py and
permission_management.py modules.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-11 00:05:57 +01:00

734 lines
24 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Castle UI Improvements Plan
**Date**: November 10, 2025
**Status**: 📋 **Planning Document**
**Related**: ACCOUNT-SYNC-AND-PERMISSION-IMPROVEMENTS.md, PERMISSIONS-SYSTEM.md
---
## Overview
Enhance the Castle permissions UI to showcase new bulk permission management and account sync features, making admin tasks faster and more intuitive.
---
## Current UI Assessment
**What's Good:**
- ✅ Clean Quasar/Vue.js structure
- ✅ Three views: By User, By Account, Equity
- ✅ Basic grant/revoke functionality
- ✅ Good visual design with icons and colors
- ✅ Admin-only protection
**What's Missing:**
- ❌ No bulk operations
- ❌ No permission analytics dashboard
- ❌ No permission templates/copying
- ❌ No account sync UI
- ❌ No user offboarding workflow
- ❌ No expiring permissions alerts
---
## Proposed Enhancements
### 1. Add "Analytics" Tab
**Purpose**: Give admins visibility into permission usage
**Features:**
- Total permissions count (by type)
- Permissions expiring soon (7 days)
- Most-permissioned accounts (top 10)
- Users with/without permissions
- Permission grant timeline chart
**UI Mockup:**
```
┌─────────────────────────────────────────────┐
│ 📊 Permission Analytics │
├─────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Total │ │ Expiring │ │
│ │ 150 │ │ 5 (7 days) │ │
│ │ Permissions │ │ │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ Permission Distribution │
│ ┌────────────────────────────────────┐ │
│ │ READ ██████ 50 (33%) │ │
│ │ SUBMIT_EXPENSE ████████ 80 (53%) │ │
│ │ MANAGE ████ 20 (13%) │ │
│ └────────────────────────────────────┘ │
│ │
│ ⚠️ Expiring Soon │
│ ┌────────────────────────────────────┐ │
│ │ alice on Expenses:Food (3 days) │ │
│ │ bob on Income:Services (5 days) │ │
│ └────────────────────────────────────┘ │
│ │
│ Top Accounts by Permissions │
│ ┌────────────────────────────────────┐ │
│ │ 1. Expenses:Food (25 permissions) │ │
│ │ 2. Expenses:Accommodation (18) │ │
│ │ 3. Income:Services (12) │ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```
**Implementation:**
- New API endpoint: `GET /api/v1/admin/permissions/analytics`
- Client-side stats display with Quasar charts
- Auto-refresh every 30 seconds
---
### 2. Bulk Permission Operations Menu
**Purpose**: Enable admins to perform bulk operations efficiently
**Features:**
- Bulk Grant (multiple users)
- Copy Permissions (template from user)
- Offboard User (revoke all)
- Close Account (revoke all on account)
**UI Mockup:**
```
┌─────────────────────────────────────────────┐
│ 🔐 Permission Management │
│ │
│ [Grant Permission ▼] [Bulk Operations ▼] │
│ │
│ ┌──────────────────────────────────┐ │
│ │ • Bulk Grant to Multiple Users │ │
│ │ • Copy Permissions from User │ │
│ │ • Offboard User (Revoke All) │ │
│ │ • Close Account (Revoke All) │ │
│ │ • Sync Accounts from Beancount │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```
---
### 3. Bulk Grant Dialog
**UI Mockup:**
```
┌───────────────────────────────────────────┐
│ 👥 Bulk Grant Permission │
├───────────────────────────────────────────┤
│ │
│ Select Users * │
│ ┌────────────────────────────────────┐ │
│ │ 🔍 Search users... │ │
│ └────────────────────────────────────┘ │
│ │
│ Selected: alice, bob, charlie (3 users) │
│ │
│ Select Account * │
│ ┌────────────────────────────────────┐ │
│ │ Expenses:Food │ │
│ └────────────────────────────────────┘ │
│ │
│ Permission Type * │
│ ┌────────────────────────────────────┐ │
│ │ Submit Expense │ │
│ └────────────────────────────────────┘ │
│ │
│ Expires (Optional) │
│ [2025-12-31 23:59:59] │
│ │
│ Notes (Optional) │
│ [Q4 2025 food team members] │
│ │
This will grant SUBMIT_EXPENSE │
│ permission to 3 users on │
│ Expenses:Food │
│ │
│ [Cancel] [Grant to 3 Users] │
└───────────────────────────────────────────┘
```
**Features:**
- Multi-select user dropdown
- Preview of operation before confirm
- Shows estimated time savings
---
### 4. Copy Permissions Dialog
**UI Mockup:**
```
┌───────────────────────────────────────────┐
│ 📋 Copy Permissions │
├───────────────────────────────────────────┤
│ │
│ Copy From (Template User) * │
│ ┌────────────────────────────────────┐ │
│ │ alice (Experienced Coordinator) │ │
│ └────────────────────────────────────┘ │
│ │
│ 📊 alice has 5 permissions: │
│ • Expenses:Food (Submit Expense) │
│ • Expenses:Food:Groceries (Submit) │
│ • Income:Services (Read) │
│ • Assets:Cash (Read) │
│ • Expenses:Utilities (Submit) │
│ │
│ Copy To (New User) * │
│ ┌────────────────────────────────────┐ │
│ │ bob (New Hire) │ │
│ └────────────────────────────────────┘ │
│ │
│ Filter by Permission Type (Optional) │
│ ☑ Submit Expense ☐ Read ☐ Manage │
│ │
│ Notes │
│ [Copied from Alice - new coordinator] │
│ │
This will copy 3 SUBMIT_EXPENSE │
│ permissions from alice to bob │
│ │
│ [Cancel] [Copy Permissions] │
└───────────────────────────────────────────┘
```
**Features:**
- Shows source user's permissions
- Filter by permission type
- Preview before copying
---
### 5. Offboard User Dialog
**UI Mockup:**
```
┌───────────────────────────────────────────┐
│ 🚪 Offboard User │
├───────────────────────────────────────────┤
│ │
│ Select User to Offboard * │
│ ┌────────────────────────────────────┐ │
│ │ charlie (Departed Employee) │ │
│ └────────────────────────────────────┘ │
│ │
│ ⚠️ Current Permissions (8 total): │
│ ┌────────────────────────────────────┐ │
│ │ • Expenses:Food (Submit Expense) │ │
│ │ • Expenses:Utilities (Submit) │ │
│ │ • Income:Services (Read) │ │
│ │ • Assets:Cash (Read) │ │
│ │ • Expenses:Accommodation (Submit) │ │
│ │ • ... 3 more │ │
│ └────────────────────────────────────┘ │
│ │
│ ⚠️ Warning: This will revoke ALL │
│ permissions for this user. They will │
│ immediately lose access to Castle. │
│ │
│ Reason for Offboarding │
│ [Employee departure - last day] │
│ │
│ [Cancel] [Revoke All (8)] │
└───────────────────────────────────────────┘
```
**Features:**
- Shows all current permissions
- Requires confirmation
- Logs reason for audit
---
### 6. Account Sync UI
**Location**: Admin Settings or Bulk Operations menu
**UI Mockup:**
```
┌───────────────────────────────────────────┐
│ 🔄 Sync Accounts from Beancount │
├───────────────────────────────────────────┤
│ │
│ Sync accounts from your Beancount ledger │
│ to Castle database for permission mgmt. │
│ │
│ Last Sync: 2 hours ago │
│ Status: ✅ Up to date │
│ │
│ Accounts in Beancount: 150 │
│ Accounts in Castle DB: 150 │
│ │
│ Options: │
│ ☐ Force full sync (re-check all) │
│ │
│ [Sync Now] │
│ │
│ Recent Sync History: │
│ ┌────────────────────────────────────┐ │
│ │ Nov 10, 2:00 PM - Added 2 accounts │ │
│ │ Nov 10, 12:00 PM - Up to date │ │
│ │ Nov 10, 10:00 AM - Added 1 account │ │
│ └────────────────────────────────────┘ │
└───────────────────────────────────────────┘
```
**Features:**
- Shows sync status
- Last sync timestamp
- Account counts
- Sync history
---
### 7. Expiring Permissions Alert
**Location**: Top of permissions page (if any expiring soon)
**UI Mockup:**
```
┌─────────────────────────────────────────────┐
│ ⚠️ 5 Permissions Expiring Soon (Next 7 Days)│
├─────────────────────────────────────────────┤
│ • alice on Expenses:Food (3 days) │
│ • bob on Income:Services (5 days) │
│ • charlie on Assets:Cash (7 days) │
│ │
│ [View All] [Extend Expiration] [Dismiss] │
└─────────────────────────────────────────────┘
```
**Features:**
- Prominent alert banner
- Shows expiring in next 7 days
- Quick actions to extend
---
### 8. Permission Templates (Future)
**Concept**: Pre-defined permission sets for common roles
**UI Mockup:**
```
┌───────────────────────────────────────────┐
│ 📝 Apply Permission Template │
├───────────────────────────────────────────┤
│ │
│ Select User * │
│ [bob] │
│ │
│ Select Template * │
│ ┌────────────────────────────────────┐ │
│ │ Food Coordinator (5 permissions) │ │
│ │ • Expenses:Food (Submit) │ │
│ │ • Expenses:Food:* (Submit) │ │
│ │ • Income:Services (Read) │ │
│ │ │ │
│ │ Accommodation Manager (8 perms) │ │
│ │ Finance Admin (15 perms) │ │
│ │ Read-Only Auditor (25 perms) │ │
│ └────────────────────────────────────┘ │
│ │
│ [Cancel] [Apply Template] │
└───────────────────────────────────────────┘
```
---
## Implementation Priority
### Phase 1: Quick Wins (This Week)
**Effort**: 2-3 days
1. **Analytics Tab** (1 day)
- Add new tab to permissions.html
- Call analytics API endpoint
- Display stats with Quasar components
2. **Bulk Grant Dialog** (1 day)
- Add multi-select user dropdown
- Call bulk grant API
- Show success/failure results
3. **Account Sync Button** (0.5 days)
- Add sync button to admin area
- Call sync API
- Show progress and results
**Impact**: Immediate productivity boost for admins
---
### Phase 2: Bulk Operations (Next Week)
**Effort**: 2-3 days
4. **Copy Permissions Dialog** (1 day)
- Template selection UI
- Preview permissions
- Copy operation
5. **Offboard User Dialog** (1 day)
- User selection with permission preview
- Confirmation with reason logging
- Bulk revoke operation
6. **Expiring Permissions Alert** (0.5 days)
- Alert banner component
- Query expiring permissions
- Quick actions
**Impact**: Major time savings for common workflows
---
### Phase 3: Polish (Later)
**Effort**: 2-3 days
7. **Permission Templates** (2 days)
- Template management UI
- Template CRUD operations
- Apply template workflow
8. **Advanced Analytics** (1 day)
- Charts and graphs
- Permission history timeline
- Usage patterns
**Impact**: Long-term ease of use
---
## Technical Implementation
### New API Endpoints Needed
```javascript
// Analytics
GET /api/v1/admin/permissions/analytics
// Bulk Operations
POST /api/v1/admin/permissions/bulk-grant
{
user_ids: ["alice", "bob", "charlie"],
account_id: "acc123",
permission_type: "submit_expense",
expires_at: "2025-12-31T23:59:59",
notes: "Q4 team"
}
POST /api/v1/admin/permissions/copy
{
from_user_id: "alice",
to_user_id: "bob",
permission_types: ["submit_expense"],
notes: "New coordinator"
}
DELETE /api/v1/admin/permissions/user/{user_id}
DELETE /api/v1/admin/permissions/account/{account_id}
// Account Sync
POST /api/v1/admin/sync-accounts
{
force_full_sync: false
}
GET /api/v1/admin/sync-accounts/status
```
### Vue.js Component Structure
```
permissions.html
├── Analytics Tab (new)
│ ├── Stats Cards
│ ├── Distribution Chart
│ ├── Expiring Soon List
│ └── Top Accounts List
├── By User Tab (existing)
│ └── Enhanced with bulk operations
├── By Account Tab (existing)
│ └── Enhanced with bulk operations
├── Equity Tab (existing)
└── Dialogs
├── Bulk Grant Dialog (new)
├── Copy Permissions Dialog (new)
├── Offboard User Dialog (new)
├── Account Sync Dialog (new)
├── Grant Permission Dialog (existing)
└── Revoke Confirmation Dialog (existing)
```
### State Management
```javascript
// Add to Vue app data
{
// Analytics
analytics: {
total: 0,
byType: {},
expiringSoon: [],
topAccounts: []
},
// Bulk Operations
bulkGrantForm: {
user_ids: [],
account_id: null,
permission_type: null,
expires_at: null,
notes: ''
},
copyPermissionsForm: {
from_user_id: null,
to_user_id: null,
permission_types: [],
notes: ''
},
offboardForm: {
user_id: null,
reason: ''
},
// Account Sync
syncStatus: {
lastSync: null,
beancountAccounts: 0,
castleAccounts: 0,
status: 'idle'
}
}
```
---
## User Experience Flow
### Onboarding New Team Member (Before vs After)
**Before** (10 minutes):
1. Open permissions page
2. Click "Grant Permission" 5 times
3. Fill form each time (user, account, type)
4. Click grant, repeat
5. Hope you didn't forget any
**After** (1 minute):
1. Click "Bulk Operations" → "Copy Permissions"
2. Select template user → Select new user
3. Click "Copy"
4. Done! ✨
**Time Saved**: 90%
---
### Quarterly Access Review (Before vs After)
**Before** (2 hours):
1. Export permissions to spreadsheet
2. Manually review each one
3. Delete expired individually
4. Update expiration dates one by one
**After** (5 minutes):
1. Click "Analytics" tab
2. See "5 Expiring Soon" alert
3. Review list, click "Extend" on relevant ones
4. Done! ✨
**Time Saved**: 96%
---
## Testing Plan
### UI Testing
```javascript
// Test bulk grant
async function testBulkGrant() {
// 1. Open bulk grant dialog
// 2. Select 3 users
// 3. Select account
// 4. Select permission type
// 5. Click grant
// 6. Verify success message
// 7. Verify permissions appear in UI
}
// Test copy permissions
async function testCopyPermissions() {
// 1. Open copy dialog
// 2. Select source user with 5 permissions
// 3. Select target user
// 4. Filter to SUBMIT_EXPENSE only
// 5. Verify preview shows 3 permissions
// 6. Click copy
// 7. Verify target user has 3 new permissions
}
// Test analytics
async function testAnalytics() {
// 1. Switch to analytics tab
// 2. Verify stats load
// 3. Verify charts display
// 4. Verify expiring permissions show
// 5. Click on expiring permission
// 6. Verify details dialog opens
}
```
### Integration Testing
```python
# Test full workflow
async def test_onboarding_workflow():
# 1. Admin syncs accounts
sync_result = await api.post("/admin/sync-accounts")
assert sync_result["accounts_added"] >= 0
# 2. Admin copies permissions from template user
copy_result = await api.post("/admin/permissions/copy", {
"from_user_id": "template",
"to_user_id": "new_user"
})
assert copy_result["copied"] > 0
# 3. Verify new user has permissions in UI
perms = await api.get(f"/admin/permissions?user_id=new_user")
assert len(perms) > 0
# 4. Check analytics reflect new permissions
analytics = await api.get("/admin/permissions/analytics")
assert analytics["total_permissions"] increased
```
---
## Accessibility
- ✅ Keyboard navigation support
- ✅ Screen reader friendly labels
- ✅ Color contrast compliance (WCAG AA)
- ✅ Focus indicators
- ✅ ARIA labels on interactive elements
---
## Mobile Responsiveness
- ✅ Analytics cards stack vertically on mobile
- ✅ Dialogs are full-screen on small devices
- ✅ Touch-friendly button sizes
- ✅ Swipe gestures for tabs
---
## Error Handling
**Bulk Grant Fails:**
```
⚠️ Bulk Grant Results
✅ Granted to 3 users
❌ Failed for 2 users:
• bob: Already has permission
• charlie: Account not found
[View Details] [Retry Failed] [Dismiss]
```
**Account Sync Fails:**
```
❌ Account Sync Failed
Could not connect to Beancount service.
Error: Connection timeout after 10s
[Retry] [Check Settings] [Dismiss]
```
---
## Performance Considerations
- **Pagination**: Load permissions in batches of 50
- **Lazy Loading**: Load analytics only when tab is viewed
- **Debouncing**: Debounce search inputs (300ms)
- **Caching**: Cache analytics for 30 seconds
- **Optimistic UI**: Show loading state immediately
---
## Security Considerations
- ✅ All bulk operations require admin key
- ✅ Confirmation dialogs for destructive actions
- ✅ Audit log all bulk operations
- ✅ Rate limiting on API endpoints
- ✅ CSRF protection on forms
---
## Documentation
**User Guide** (to create):
1. How to bulk grant permissions
2. How to copy permissions (templating)
3. How to offboard a user
4. How to sync accounts
5. How to use analytics dashboard
**Admin Guide** (to create):
1. When to use bulk operations
2. Best practices for permission templates
3. How to monitor permission usage
4. Troubleshooting sync issues
---
## Success Metrics
**Measure after deployment:**
- Time to onboard new user: 10min → 1min
- Time for access review: 2hr → 5min
- Admin satisfaction score: 6/10 → 9/10
- Support tickets for permissions: -70%
- Permissions granted per month: +40%
---
## Summary
This UI improvement plan focuses on:
1. **Quick Wins**: Analytics and bulk grant (2-3 days)
2. **Bulk Operations**: Copy, offboard, sync (2-3 days)
3. **Polish**: Templates and advanced features (later)
**Total Time**: ~5-6 days for Phase 1 & 2
**Impact**: 50-70% reduction in admin time
**ROI**: Immediate productivity boost
The enhancements leverage the new backend features we built (account sync, bulk permission management) and make them accessible through an intuitive UI, significantly improving the admin experience.
---
**Document Version**: 1.0
**Last Updated**: November 10, 2025
**Status**: Ready for Implementation