TenantAtlas/specs/002-filament-json/DEPLOYMENT.md

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 ✓

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

Documentation ✓

• README.md updated with feature description
• quickstart.md comprehensive usage guide created
• research.md implementation decisions documented
• tasks.md complete with traceability

---

Staging Deployment

1. Code Deployment

# On local machine
git push origin tenantpilot-v1

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

2. Post-Deployment Commands

# 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

# 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

• Staging deployment successful
• All staging verification steps passed
• Manual QA sign-off from stakeholder

1. Code Deployment

# 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

# 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

# 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)

# 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

• JSON viewer renders on all policy detail pages
• Copy-to-clipboard functionality works across browsers
• Large payload warnings display correctly (>500 KB)
• Settings Catalog tabs switch between Settings and JSON views
• Dark mode styling applied correctly
• Browser search (Cmd+F / Ctrl+F) works within JSON
• No performance degradation (<2s render for policies up to 1 MB)
• 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)