# Deployment Checklist - Feature 002-filament-json

## Overview
This checklist covers the deployment of the Policy JSON Viewer feature to staging and production environments.

## Pre-Deployment Verification

### Code Quality ✓
- [X] All tests passing locally (Pest suite)
- [X] Code formatted with Laravel Pint
- [X] Git changes reviewed (no forbidden files modified)
- [X] Constitution compliance verified (UI-only, no behavioral changes)

### Documentation ✓
- [X] README.md updated with feature description
- [X] quickstart.md comprehensive usage guide created
- [X] research.md implementation decisions documented
- [X] tasks.md complete with traceability

---

## Staging Deployment

### 1. Code Deployment
```bash
# On local machine
git push origin tenantpilot-v1

# Dokploy will auto-deploy to staging
# Or manually trigger via Dokploy dashboard
```

### 2. Post-Deployment Commands
```bash
# SSH into staging server or use Dokploy exec
./vendor/bin/sail composer install --no-dev --optimize-autoloader
./vendor/bin/sail artisan config:clear
./vendor/bin/sail artisan view:clear
./vendor/bin/sail artisan route:clear
./vendor/bin/sail artisan cache:clear

# Verify assets published (should already exist from composer install)
ls -la public/css/pepperfm/filament-json/
```

### 3. Verification Steps

#### A. Basic Functionality
- [ ] Navigate to `/admin/policies` (policy list)
- [ ] Click any policy to view detail page
- [ ] Verify "Policy Snapshot (JSON)" section appears (or JSON tab for Settings Catalog policies)
- [ ] Verify JSON renders with pretty-print formatting
- [ ] Verify monospace font and gray background styling
- [ ] Verify scrollable container (horizontal + vertical)

#### B. Copy Functionality
- [ ] Click "Copy" button on JSON viewer
- [ ] Verify success message: "JSON copied to clipboard!"
- [ ] Paste into text editor (Cmd+V / Ctrl+V)
- [ ] Verify JSON structure intact with proper formatting

#### C. Large Payload Handling
- [ ] Find or create policy with >500 KB snapshot (512,000 bytes)
- [ ] Verify warning badge appears: "⚠️ Large payload (XXX KB). Section auto-collapsed for performance."
- [ ] Verify section collapsed by default
- [ ] Expand section, verify JSON still renders correctly

#### D. Settings Catalog Tabs
- [ ] Navigate to Settings Catalog policy (type contains "settings" or "catalog")
- [ ] Verify Tabs component appears with "Settings" and "JSON" tabs
- [ ] Click "Settings" tab → verify normalized settings table renders
- [ ] Click "JSON" tab → verify JSON viewer appears
- [ ] Verify tab switching works smoothly

#### E. Dark Mode
- [ ] Toggle dark mode in browser/Filament
- [ ] Verify JSON viewer background changes (gray-50 → gray-900)
- [ ] Verify border color adjusts (gray-200 → gray-700)
- [ ] Verify text remains readable

#### F. Browser Search
- [ ] Open JSON viewer
- [ ] Use Cmd+F (Mac) or Ctrl+F (Windows)
- [ ] Search for specific key or value in JSON
- [ ] Verify browser highlights matches within JSON container

#### G. Null/Missing Snapshot Handling
- [ ] Find policy with no versions/snapshots
- [ ] Verify message displays: "No snapshot available"
- [ ] Verify no errors in browser console

### 4. Performance Testing
```bash
# SSH into staging
./vendor/bin/sail artisan test

# Check for regressions
# Expected: Same pass/fail rate as before deployment
```

- [ ] Load policy with 100 KB snapshot → verify <1s render
- [ ] Load policy with 500 KB snapshot → verify <2s render
- [ ] Load policy with 1 MB snapshot → verify auto-collapse prevents freeze

### 5. Browser Console Check
- [ ] Open browser DevTools Console (F12 → Console tab)
- [ ] Navigate through policy detail pages
- [ ] Verify no JavaScript errors
- [ ] Verify no 404s for CSS assets

---

## Production Deployment

### Prerequisites
- [X] Staging deployment successful
- [X] All staging verification steps passed
- [X] Manual QA sign-off from stakeholder

### 1. Code Deployment
```bash
# Merge to production branch
git checkout main
git merge tenantpilot-v1
git push origin main

# Dokploy auto-deploys to production
# Or manually trigger via Dokploy dashboard
```

### 2. Post-Deployment Commands
```bash
# Same as staging
./vendor/bin/sail composer install --no-dev --optimize-autoloader
./vendor/bin/sail artisan config:clear
./vendor/bin/sail artisan view:clear
./vendor/bin/sail artisan route:clear
./vendor/bin/sail artisan cache:clear
```

### 3. Smoke Testing (Production)
- [ ] Test 3-5 representative policies (various types)
- [ ] Verify JSON viewer renders
- [ ] Verify copy functionality works
- [ ] Verify no errors in browser console

### 4. Monitor for Issues
- [ ] Check Laravel logs: `storage/logs/laravel.log`
- [ ] Monitor application performance (response times)
- [ ] Watch for user-reported issues (first 24 hours)

---

## Rollback Plan

### If Critical Issues Found

#### 1. Code Rollback
```bash
# Revert the feature branch merge
git revert <merge-commit-hash>
git push origin main

# Or reset to previous commit
git reset --hard <previous-commit-hash>
git push origin main --force
```

#### 2. Package Removal (Optional)
```bash
# If package causing issues
./vendor/bin/sail composer remove pepperfm/filament-json
./vendor/bin/sail artisan config:clear
./vendor/bin/sail artisan view:clear

# Remove published assets
rm -rf public/css/pepperfm/filament-json/
```

#### 3. Database Rollback
**Not applicable** - this feature has no migrations or database changes.

#### 4. Verify Rollback
- [ ] Policy detail pages render without JSON viewer
- [ ] Normalized settings still display correctly
- [ ] No errors in logs or browser console

---

## Deployment Timeline

### Estimated Duration
- **Staging**: ~30 minutes (deployment + verification)
- **Production**: ~20 minutes (deployment + smoke testing)
- **Total**: ~50 minutes

### Recommended Schedule
- **Staging**: Deploy during business hours for immediate testing
- **Production**: Deploy during low-traffic window (if applicable) or business hours with monitoring

---

## Success Criteria

- [X] JSON viewer renders on all policy detail pages
- [X] Copy-to-clipboard functionality works across browsers
- [X] Large payload warnings display correctly (>500 KB)
- [X] Settings Catalog tabs switch between Settings and JSON views
- [X] Dark mode styling applied correctly
- [X] Browser search (Cmd+F / Ctrl+F) works within JSON
- [X] No performance degradation (<2s render for policies up to 1 MB)
- [X] No new errors in logs or browser console

---

## Known Limitations

1. **Search Within JSON**: Relies on browser native find-in-page (Cmd+F / Ctrl+F), not a custom search UI.
2. **Download Action**: Not implemented in MVP - copy functionality deemed sufficient.
3. **Package Usage**: pepperfm/filament-json installed but not used in final implementation (native Filament approach chosen for better infolist integration).

---

## Support & Troubleshooting

### Issue: JSON not rendering
**Check**:
- Browser console for JavaScript errors
- Laravel logs for PHP errors
- Verify snapshot exists: `$record->versions()->orderByDesc('captured_at')->value('snapshot')`

### Issue: Copy button not working
**Check**:
- Browser supports Clipboard API (all modern browsers)
- HTTPS required for Clipboard API (localhost exempt)
- Check browser console for permissions errors

### Issue: Large payload freezing browser
**Check**:
- Verify payload size detection logic: `strlen(json_encode($state)) > 512000`
- Verify auto-collapse enabled for large payloads
- Consider reducing max-h-96 to max-h-64 for very large payloads

---

## Contact

For deployment issues or questions:
- **Developer**: Ahmed Darrazi
- **Documentation**: `specs/002-filament-json/quickstart.md`
- **Repository**: TenantAtlas (tenantpilot-v1 branch)