# 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