navidocs/server/docs/ADMIN_UI_IMPLEMENTATION_PLAN.md

Admin UI Implementation Plan

Overview

Based on persona analysis, implementing a progressive disclosure UI system that starts simple and reveals complexity based on user needs.

Implementation Strategy

Phase 1: Foundation (CURRENT)

1. Permission Templates System

Backend: Create pre-built role templates

• Captain - Manager level, full vessel access
• Crew Member - Viewer level, shift-based
• Maintenance Contractor - Editor level, temporary (7 days)
• Inspector - Viewer level, temporary (1 day)
• Property Manager - Admin level, organization-wide

Files to create:

• services/permission-templates.service.js
• routes/permission-templates.routes.js
• Migration for templates table

2. Simple Admin Dashboard

Features:

• Quick user invitation (email → auto-assign template)
• Active permissions list
• Recent activity feed
• Mobile-responsive cards layout

Tech Stack: Vanilla JS + Tailwind CSS (lightweight, no framework overhead)

3. Mobile-First Permission Grant

Captain's Quick Access:

• Scan QR code to onboard crew
• Select template (Crew/Contractor/Inspector)
• Set duration (Shift/Day/Week/Custom)
• Send invitation

UI Components:

• Large touch targets (min 44px)
• High contrast mode for outdoor use
• Offline capability with service worker

---

File Structure

server/
├── services/
│   ├── permission-templates.service.js  [NEW]
│   └── quick-invite.service.js           [NEW]
├── routes/
│   ├── admin.routes.js                   [NEW]
│   └── quick-invite.routes.js            [NEW]
├── db/migrations/
│   └── 009_permission_templates.sql      [NEW]
└── public/admin/                         [NEW]
    ├── index.html                        Simple admin dashboard
    ├── quick-grant.html                  Mobile permission grant
    ├── css/admin.css                     Tailwind + custom
    └── js/
        ├── admin-dashboard.js
        ├── quick-grant.js
        └── permission-visualizer.js

client/ (if separate React app exists)
├── src/
    └── pages/
        └── admin/                        [NEW]
            ├── Dashboard.jsx
            ├── PermissionGrant.jsx
            ├── BulkOperations.jsx
            └── Analytics.jsx

---

API Endpoints to Implement

Permission Templates

GET    /api/admin/templates              List all permission templates
POST   /api/admin/templates              Create custom template
GET    /api/admin/templates/:id          Get template details
PUT    /api/admin/templates/:id          Update template
DELETE /api/admin/templates/:id          Delete template

Quick Invite

POST   /api/admin/quick-invite           Send invitation with template
GET    /api/admin/invitations            List pending invitations
DELETE /api/admin/invitations/:id        Cancel invitation

Admin Dashboard

GET    /api/admin/stats                  Dashboard statistics
GET    /api/admin/activity               Recent activity feed
GET    /api/admin/users                  List users with permissions
POST   /api/admin/users/:id/revoke-all   Emergency revoke all access

Bulk Operations

POST   /api/admin/bulk/grant             Grant permissions to multiple users
POST   /api/admin/bulk/revoke            Revoke from multiple users
POST   /api/admin/bulk/import            CSV import
GET    /api/admin/bulk/export            CSV export

---

Database Schema

permission_templates table

CREATE TABLE permission_templates (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT,
  permission_level TEXT NOT NULL,  -- viewer, editor, manager, admin
  default_duration_hours INTEGER,  -- NULL = permanent
  is_system BOOLEAN DEFAULT 0,     -- System templates can't be deleted
  metadata TEXT,                    -- JSON: {icon, color, restrictions}
  created_by TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);

invitations table

CREATE TABLE invitations (
  id TEXT PRIMARY KEY,
  email TEXT NOT NULL,
  template_id TEXT REFERENCES permission_templates(id),
  entity_id TEXT,
  invited_by TEXT REFERENCES users(id),
  status TEXT DEFAULT 'pending',   -- pending, accepted, expired, cancelled
  expires_at INTEGER NOT NULL,
  accepted_at INTEGER,
  created_at INTEGER NOT NULL
);

---

UI Modes Implementation

Auto-detect mode based on:

1. Number of properties/entities (< 10 = Simple, 10-50 = Standard, 50+ = Enterprise)
2. Number of users (< 20 = Simple, 20-100 = Standard, 100+ = Enterprise)
3. API usage (any API calls = show Developer mode option)

Mode switching:

• Allow manual override
• Save preference per user
• Keyboard shortcut: Ctrl/Cmd + Shift + M to toggle modes

---

Success Metrics

Performance Targets:

• Page load: < 2s on 3G
• Time to interactive: < 3s
• Permission grant: < 500ms API response
• Bulk operation (100 users): < 5s

UX Targets (from persona analysis):

• Captain grants access: < 30 seconds
• Single agency setup: < 5 minutes
• Bulk onboard 20 users: < 3 minutes
• Mobile permission check: < 2 taps

---

Progressive Enhancement Strategy

1. Core HTML - Works without JS (forms submit via POST)
2. + CSS - Mobile-responsive, accessible
3. + Basic JS - AJAX forms, client-side validation
4. + Advanced JS - Real-time updates, drag-drop, visualizations
5. + PWA - Offline support, push notifications

---

Security Considerations

1. CSRF protection on all admin endpoints
2. Rate limiting on invitation endpoints (max 10/hour per user)
3. Audit logging for all permission changes
4. Email verification before accepting invitations
5. IP whitelisting option for enterprise users
6. 2FA requirement for bulk operations (optional)

---

Next Steps

1. ✅ Create persona requirements analysis (DONE)
2. Create permission templates service
3. Build simple admin dashboard
4. Implement quick invite system
5. Add mobile-optimized permission grant UI
6. Create bulk operations panel
7. Build analytics/reporting
8. Add visual permission builder (Phase 4)

---

This plan follows the progressive disclosure principle: start simple, add complexity as needed.