castle/docs/UI-IMPROVEMENTS-PLAN.md

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

// 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

// 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

// 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

# 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