From b8ff4e91c3271a76f18d4ec86023e24c43d5b619 Mon Sep 17 00:00:00 2001 From: Danny Stocker Date: Fri, 14 Nov 2025 16:29:48 +0100 Subject: [PATCH] Add parallel Codex + Gemini review framework - Both reviewers work simultaneously (5-10 min total) - Codex: Security + architecture deep dive - Gemini: Performance + UX + accessibility analysis - Services running: Backend (8001) + Frontend (3200) - Output: 2 comprehensive reports with fixes + estimates --- GEMINI_REVIEW_PROMPT.txt | 299 +++++++++++++++++++++++++++++++++++++++ LAUNCH_REVIEWS.md | 181 ++++++++++++++++++++++++ run-parallel-reviews.sh | 103 ++++++++++++++ 3 files changed, 583 insertions(+) create mode 100644 GEMINI_REVIEW_PROMPT.txt create mode 100644 LAUNCH_REVIEWS.md create mode 100755 run-parallel-reviews.sh diff --git a/GEMINI_REVIEW_PROMPT.txt b/GEMINI_REVIEW_PROMPT.txt new file mode 100644 index 0000000..9897514 --- /dev/null +++ b/GEMINI_REVIEW_PROMPT.txt @@ -0,0 +1,299 @@ +Analyze the NaviDocs boat management platform for performance optimization and user experience quality. + +**Context:** +- Codebase: /home/setup/navidocs +- Stack: Vue 3 + Vite, Express.js, SQLite +- Target: €800K-€1.5M yacht market (premium UX expectations) +- Users: Boat owners, captains, crew, management companies +- Environment: Marine (bright sunlight, gloves, wet hands, boat vibrations) + +**Your Focus Areas:** + +## 1. Performance Analysis + +**Frontend Performance:** +- Bundle size analysis (target: <500KB gzipped) +- Code splitting effectiveness (lazy-loaded routes?) +- Image optimization (WebP, responsive images, lazy loading) +- JavaScript execution time (large components causing jank?) +- Memory leaks (event listeners cleaned up on unmount?) +- Vite build config optimization + +**Commands to run:** +```bash +cd /home/setup/navidocs + +# Build and analyze +npm run build +du -sh dist/ +find dist/assets -name "*.js" -exec du -h {} \; | sort -h + +# Check for lazy loading +grep -r "import.*from.*views" client/src/router/ + +# Find large components (>500 lines = performance risk) +find client/src -name "*.vue" -exec wc -l {} \; | awk '$1 > 500 {print}' +``` + +**Backend Performance:** +- Database query efficiency (N+1 queries, missing indexes) +- API response times (should be <200ms p95) +- Pagination implementation (avoid loading 1000+ rows) +- Response compression (gzip enabled?) +- Caching strategy (Redis used? HTTP cache headers?) + +**Commands to run:** +```bash +# Check for N+1 queries (loop + db query = bad) +grep -r "for.*of\|forEach" server/routes/ -A 5 | grep "db.prepare" + +# Find missing indexes +sqlite3 server/navidocs.db "SELECT name FROM sqlite_master WHERE type='index';" + +# Check pagination (should use LIMIT/OFFSET) +grep -r "\.all(" server/routes/ | wc -l # High count = potential issue +``` + +**Deliverable:** +- Lighthouse Performance score estimate (based on code analysis) +- Specific bottlenecks with file:line references +- Quick wins (easy optimizations with high impact) +- Bundle size breakdown (which chunks are largest?) + +--- + +## 2. User Experience (UX) Analysis + +**Marine Environment Considerations:** +- Touch targets: Are all buttons ≥60×60px? (glove-friendly) +- Contrast ratio: Is text readable in direct sunlight? (WCAG AAA = 7:1) +- Font sizes: Are key metrics ≥32px? (Garmin-style glanceability) +- Glass morphism performance: Is backdrop-filter causing lag? + +**Commands to run:** +```bash +# Find small touch targets +grep -r "width.*px\|height.*px" client/src/components/ | grep -E "width: [1-4][0-9]px|height: [1-4][0-9]px" + +# Check for low contrast (search for light colors on light backgrounds) +grep -r "color.*#[A-F0-9]\{6\}" client/src --include="*.vue" | grep -E "fff|eee|ddd" + +# Find small fonts (<16px = hard to read) +grep -r "font-size.*px" client/src | grep -E "[0-9]{1}px|1[0-5]px" +``` + +**Interaction Design:** +- Loading states: Does every async action show feedback? +- Error handling: Are errors user-friendly? (not technical jargon) +- Empty states: Are "no data" screens helpful? (actionable CTAs) +- Navigation clarity: Can users find features intuitively? + +**Accessibility (a11y):** +- Keyboard navigation: Can you tab through all controls? +- ARIA labels: Do icons have screen-reader text? +- Color blindness: Is information conveyed beyond color? +- Focus indicators: Are they visible and clear? + +**Commands to run:** +```bash +# Find missing ARIA labels +grep -r "300 lines = hard to maintain, bugs likely) +- Is there duplicated code? (inconsistent UX across modules) +- Are error boundaries implemented? (crashes break UX) + +**State Management:** +- Is global state properly managed? (Pinia store used?) +- Are loading/error states handled consistently? +- Do forms validate properly? (prevent user frustration) + +**Visual Consistency:** +- Is there a design system? (consistent spacing, colors, typography) +- Are magic numbers avoided? (CSS values in variables) +- Do all modules look coherent? (or patchwork of different styles) + +**Commands to run:** +```bash +# Find inconsistent spacing (magic numbers in CSS) +grep -r "margin:.*px\|padding:.*px" client/src | grep -v "var(--" | wc -l + +# Find duplicate code +npx jscpd client/src --min-lines 10 --min-tokens 50 + +# Find global state scattered in components (antipattern) +grep -r "ref(\|reactive(" client/src/views/ | wc -l # High count = state not centralized +``` + +--- + +## 4. Specific NaviDocs Features to Test + +**Test these user flows (if services running):** + +1. **Camera Module** (http://localhost:3200/cameras) + - Do thumbnails load quickly? + - Is there a loading skeleton? + - What happens when camera offline? (error state clear?) + +2. **Inventory Module** (http://localhost:3200/inventory) + - Photo upload: Is there drag-drop? Progress bar? + - Large lists: Is there virtualization? Infinite scroll? + - Search: Debounced? Shows "no results" clearly? + +3. **Maintenance Timeline** (http://localhost:3200/timeline) + - Does it load quickly with 1000+ events? + - Is future/past navigation clear? + - Mobile: Can you swipe between dates? + +4. **Dashboard** (http://localhost:3200/) + - Glanceable metrics: Large fonts? Color-coded? + - Weather widget: Loads fast? Cached? + - Quick actions: Thumb-reachable on mobile? + +--- + +## Output Format + +Generate: `/home/setup/navidocs/reviews/GEMINI_PERFORMANCE_UX_REPORT.md` + +**Structure:** + +```markdown +# Gemini Performance & UX Review - NaviDocs + +**Reviewed:** 2025-11-14 +**Model:** Gemini 2.0 Flash Thinking +**Focus:** Performance optimization + User experience quality + +--- + +## Executive Summary + +**Performance Score:** 7.2/10 (Good, needs optimization) +**UX Score:** 8.1/10 (Strong, minor accessibility gaps) + +[2-3 paragraph summary of findings] + +--- + +## Performance Issues + +### 🔴 Critical (Blocks User Action) +1. **Large Bundle Size (789 KB gzipped)** + - **Impact:** 5-8 second load on 3G connection + - **Root Cause:** All routes loaded upfront, no code splitting + - **Fix:** + ```javascript + // client/src/router/index.js + // BEFORE + import DocumentView from './views/DocumentView.vue' + + // AFTER + component: () => import('./views/DocumentView.vue') + ``` + - **Effort:** 30 minutes (convert 9 routes) + +### 🟡 High Priority (Degrades Experience) +2. **N+1 Query in Inventory Endpoint** + - **File:** `server/routes/inventory.js:78` + - **Impact:** 200ms → 2000ms with 100 items + - **Fix:** Use JOIN instead of loop + - **Effort:** 1 hour + +[Continue...] + +--- + +## UX Issues + +### 🔴 Critical (Unusable in Marine Environment) +1. **Touch Targets Too Small (32×32px)** + - **Files:** + - `client/src/components/ContactsModule.vue:45` (delete icon) + - `client/src/components/InventoryModule.vue:89` (edit button) + - **Impact:** Impossible to tap with gloves + - **Fix:** Increase to 60×60px minimum + - **Effort:** 15 minutes + +### 🟡 High Priority (Accessibility Issue) +2. **Missing ARIA Labels (14 buttons)** + - **Impact:** Screen readers can't identify actions + - **Fix:** Add `aria-label` to icon-only buttons + - **Effort:** 30 minutes + +[Continue...] + +--- + +## Quick Wins (High Impact, Low Effort) + +| Fix | Impact | Effort | ROI | +|-----|--------|--------|-----| +| Enable Vite gzip compression | -40% bundle size | 5 min | ⭐⭐⭐⭐⭐ | +| Add loading skeletons | +20% perceived speed | 1 hr | ⭐⭐⭐⭐ | +| Increase touch targets to 60px | Marine usability | 15 min | ⭐⭐⭐⭐⭐ | +| Add database indexes | -80% query time | 30 min | ⭐⭐⭐⭐⭐ | + +--- + +## Lighthouse Score Projection + +| Metric | Current (Estimated) | After Fixes | Target | +|--------|---------------------|-------------|--------| +| Performance | 68 | 92 | >90 | +| Accessibility | 81 | 96 | >90 | +| Best Practices | 87 | 95 | >90 | +| SEO | 92 | 100 | >90 | + +--- + +## Total Effort Estimate + +| Priority | Issues | Hours | Cost (€80/hr) | +|----------|--------|-------|---------------| +| Critical | 3 | 4 hrs | €320 | +| High | 8 | 12 hrs | €960 | +| Medium | 12 | 16 hrs | €1,280 | +| **Total** | **23** | **32 hrs** | **€2,560** | + +--- + +## Recommendations Priority Order + +1. **Week 1:** Fix critical performance issues (bundle splitting, N+1 queries, indexes) +2. **Week 2:** Fix marine UX issues (touch targets, contrast, font sizes) +3. **Week 3:** Accessibility improvements (ARIA, keyboard nav) +4. **Week 4:** Polish (animations, micro-interactions, loading states) + +--- + +## Conclusion + +NaviDocs has a solid foundation but needs optimization for marine environments and performance at scale. Most issues are quick fixes with high ROI. + +**Most Critical Fix:** Increase touch targets to 60×60px (15 minutes, massive UX improvement) +**Biggest Performance Win:** Add database indexes (30 minutes, 10× query speedup) +``` + +--- + +**Start your analysis now. Be thorough but actionable. Focus on fixes that matter to yacht owners using the app in real marine conditions (bright sun, gloves, boat motion).** diff --git a/LAUNCH_REVIEWS.md b/LAUNCH_REVIEWS.md new file mode 100644 index 0000000..e69e42d --- /dev/null +++ b/LAUNCH_REVIEWS.md @@ -0,0 +1,181 @@ +# Launch Parallel Code Reviews - Quick Guide + +## ✅ Services Started + +**Backend:** http://localhost:3201 (Node.js Express) +**Frontend:** http://localhost:3200 (Vite dev server) + +**Process IDs:** +- Server: Check with `ps aux | grep "node index.js"` +- Client: Check with `ps aux | grep vite` + +**Logs:** +- Backend: `/tmp/navidocs-server.log` +- Frontend: `/tmp/navidocs-client.log` + +--- + +## 🚀 Launch Reviews (2 Options) + +### **Option 1: Automated Parallel Reviews** + +Both Codex and Gemini review simultaneously (5-10 minutes): + +```bash +cd /home/setup/navidocs +./run-parallel-reviews.sh +``` + +This will: +- ✅ Check services are running +- 🤖 Launch Codex review (security + architecture) +- 💎 Launch Gemini review (performance + UX) +- 📊 Generate 2 reports in `reviews/` directory + +--- + +### **Option 2: Manual Reviews** + +**For Codex (if you have codex CLI):** +```bash +cd /home/setup/navidocs +cat CODEX_SIMPLE_PROMPT.txt | codex --model gpt-5-high --max-tokens 16000 > reviews/codex_manual.md +``` + +**For Gemini (using gemini CLI):** +```bash +cd /home/setup/navidocs +cat GEMINI_REVIEW_PROMPT.txt | gemini chat > reviews/gemini_manual.md +``` + +--- + +## 📋 What Each Reviewer Focuses On + +### **Codex GPT-5 High:** +- 🔒 **Security:** SQL injection, XSS, auth bypasses, file upload vulnerabilities +- 🏗️ **Architecture:** Code organization, separation of concerns, component design +- 📝 **Code Quality:** Naming, error handling, function complexity +- ⚙️ **Best Practices:** OWASP Top 10, RBAC, secrets management + +### **Gemini 2.0 Flash Thinking:** +- ⚡ **Performance:** Bundle size, lazy loading, N+1 queries, database indexes +- 🎨 **UX/UI:** Touch targets, contrast, font sizes, loading states +- ♿ **Accessibility:** ARIA labels, keyboard nav, screen readers +- 📱 **Mobile:** Responsive design, marine environment (gloves, sunlight) + +--- + +## 📊 Expected Output + +Both reviews will generate markdown reports in `reviews/`: + +``` +reviews/ +├── codex_20251114_162730.md (Security + Architecture) +└── gemini_20251114_162730.md (Performance + UX) +``` + +**Report Format:** +- Executive summary (rating 1-10) +- Critical issues (🔴 must fix before launch) +- High priority issues (🟡 degrades experience) +- Medium/low priority issues +- Code examples (before/after fixes) +- Effort estimates (hours + cost at €80/hr) + +--- + +## 🔧 Troubleshooting + +**If services aren't running:** +```bash +# Check process status +ps aux | grep -E "node index|vite" + +# View logs +tail -f /tmp/navidocs-server.log +tail -f /tmp/navidocs-client.log + +# Restart if needed +cd /home/setup/navidocs +./start-all.sh +``` + +**If Codex CLI not found:** +```bash +# Install Codex CLI (if available) +npm install -g @anthropic/codex-cli + +# Or use API directly +# Paste CODEX_SIMPLE_PROMPT.txt into your preferred Codex interface +``` + +**If Gemini CLI not found:** +```bash +# Gemini CLI should be installed +which gemini + +# If not, check installation +gemini --version + +# Or run manually +cat GEMINI_REVIEW_PROMPT.txt | gemini chat +``` + +--- + +## ⏱️ Timeline + +**Automated Reviews (Parallel):** 5-10 minutes total +- Codex: 5-7 minutes (deep security scan) +- Gemini: 3-5 minutes (performance analysis) + +**Manual Reviews:** 2-3 hours per reviewer +- Read prompts +- Run audit commands +- Analyze code +- Write detailed reports + +--- + +## 🎯 Next Steps After Reviews + +1. **Read both reports** (look for 🔴 critical issues first) +2. **Merge findings** into single action plan +3. **Fix critical issues** (usually <4 hours total) +4. **Re-run reviews** to verify fixes +5. **Commit improvements** to GitHub + +--- + +## 📈 Success Metrics + +**Security:** +- 0 SQL injection vulnerabilities +- 0 hardcoded secrets +- 100% routes with authentication +- 0 critical npm audit issues + +**Performance:** +- Bundle size <500KB gzipped +- API responses <200ms p95 +- Lighthouse score >90 all categories +- Database queries with indexes + +**UX:** +- Touch targets ≥60×60px (glove-friendly) +- Contrast ratio ≥7:1 (sunlight readable) +- ARIA labels on all interactive elements +- 0 horizontal scroll on mobile + +--- + +## 🚀 Ready to Launch Reviews! + +```bash +cd /home/setup/navidocs +./run-parallel-reviews.sh +``` + +The reviewers will handle everything. Sit back and wait for comprehensive reports! ☕ diff --git a/run-parallel-reviews.sh b/run-parallel-reviews.sh new file mode 100755 index 0000000..a63253d --- /dev/null +++ b/run-parallel-reviews.sh @@ -0,0 +1,103 @@ +#!/bin/bash + +# NaviDocs Parallel Code Review - Codex + Gemini +# Both AI reviewers work simultaneously on different aspects + +set -e + +echo "╔═══════════════════════════════════════════════════════════════╗" +echo "║ NaviDocs Parallel Code Review - Codex + Gemini ║" +echo "╚═══════════════════════════════════════════════════════════════╝" +echo "" + +cd /home/setup/navidocs + +# Create reviews directory +mkdir -p reviews +TIMESTAMP=$(date +%Y%m%d_%H%M%S) + +echo "🚀 NaviDocs Services Status:" +echo " Backend: http://localhost:3201 ($(curl -s http://localhost:3201/health > /dev/null && echo "✅ Running" || echo "❌ Down"))" +echo " Frontend: http://localhost:3200 ($(curl -s http://localhost:3200 > /dev/null && echo "✅ Running" || echo "❌ Down"))" +echo "" + +echo "📋 Review Plan:" +echo " • Codex GPT-5: Security + Architecture deep dive" +echo " • Gemini 2.0 Flash Thinking: Performance + UX analysis" +echo "" + +# Launch Codex review in background +echo "🤖 Starting Codex review (security & architecture focus)..." +{ + echo "# Codex Review - Security & Architecture Focus" > reviews/codex_${TIMESTAMP}.md + echo "" >> reviews/codex_${TIMESTAMP}.md + echo "**Started:** $(date)" >> reviews/codex_${TIMESTAMP}.md + echo "**Model:** GPT-5 High" >> reviews/codex_${TIMESTAMP}.md + echo "" >> reviews/codex_${TIMESTAMP}.md + + # If codex CLI exists, use it + if command -v codex &> /dev/null; then + cat CODEX_SIMPLE_PROMPT.txt | codex --model gpt-5-high --max-tokens 16000 >> reviews/codex_${TIMESTAMP}.md 2>&1 + else + echo "⚠️ Codex CLI not found - skipping automated review" >> reviews/codex_${TIMESTAMP}.md + echo "" >> reviews/codex_${TIMESTAMP}.md + echo "**Manual review required. Use this prompt:**" >> reviews/codex_${TIMESTAMP}.md + cat CODEX_SIMPLE_PROMPT.txt >> reviews/codex_${TIMESTAMP}.md + fi + + echo "✅ Codex review saved to reviews/codex_${TIMESTAMP}.md" +} & +CODEX_PID=$! + +# Launch Gemini review in background +echo "💎 Starting Gemini review (performance & UX focus)..." +{ + echo "# Gemini Review - Performance & UX Focus" > reviews/gemini_${TIMESTAMP}.md + echo "" >> reviews/gemini_${TIMESTAMP}.md + echo "**Started:** $(date)" >> reviews/gemini_${TIMESTAMP}.md + echo "**Model:** Gemini 2.0 Flash Thinking" >> reviews/gemini_${TIMESTAMP}.md + echo "" >> reviews/gemini_${TIMESTAMP}.md + + # Use gemini CLI + if command -v gemini &> /dev/null; then + cat GEMINI_REVIEW_PROMPT.txt | gemini chat >> reviews/gemini_${TIMESTAMP}.md 2>&1 + else + echo "⚠️ Gemini CLI not found - skipping automated review" >> reviews/gemini_${TIMESTAMP}.md + echo "" >> reviews/gemini_${TIMESTAMP}.md + echo "**Manual review required. Use this prompt:**" >> reviews/gemini_${TIMESTAMP}.md + cat GEMINI_REVIEW_PROMPT.txt >> reviews/gemini_${TIMESTAMP}.md + fi + + echo "✅ Gemini review saved to reviews/gemini_${TIMESTAMP}.md" +} & +GEMINI_PID=$! + +echo "" +echo "⏳ Waiting for reviews to complete (5-10 minutes)..." +echo " Codex PID: $CODEX_PID" +echo " Gemini PID: $GEMINI_PID" +echo "" + +# Wait for both to complete +wait $CODEX_PID +wait $GEMINI_PID + +echo "" +echo "╔═══════════════════════════════════════════════════════════════╗" +echo "║ ✅ Both Reviews Complete! ║" +echo "╚═══════════════════════════════════════════════════════════════╝" +echo "" +echo "📄 Review Reports:" +echo " • Codex: reviews/codex_${TIMESTAMP}.md" +echo " • Gemini: reviews/gemini_${TIMESTAMP}.md" +echo "" +echo "📊 Combined Stats:" +wc -l reviews/codex_${TIMESTAMP}.md reviews/gemini_${TIMESTAMP}.md +echo "" +echo "🔍 To view:" +echo " cat reviews/codex_${TIMESTAMP}.md" +echo " cat reviews/gemini_${TIMESTAMP}.md" +echo "" +echo " Or merge into single report:" +echo " cat reviews/codex_${TIMESTAMP}.md reviews/gemini_${TIMESTAMP}.md > reviews/combined_${TIMESTAMP}.md" +echo ""