navidocs/CODEX_REVIEW_PROMPT.md

Codex GPT-5 High - NaviDocs Codebase Comprehensive Review

Date: 2025-11-14 Repository: /home/setup/navidocs Branch: navidocs-cloud-coordination Evaluation Scope: Style, Substance, Code Quality, Usability, Value, Architecture

---

Mission: Comprehensive Codebase Audit & Improvement Recommendations

You are tasked with performing an exhaustive review of the NaviDocs boat documentation management platform. This is a Vue 3 + Express.js + SQLite application targeting the €800K-€1.5M yacht market (Jeanneau Prestige, Sunseeker).

Your Role: Expert code reviewer with expertise in:

• Modern JavaScript/TypeScript (Vue 3 Composition API, Express.js)
• Database design (SQLite schema optimization, indexing strategies)
• Security best practices (OWASP Top 10, authentication, authorization)
• Performance optimization (bundle size, lazy loading, caching)
• UX/UI design patterns (Apple HIG, Material Design, accessibility)
• Software architecture (separation of concerns, testability, maintainability)

---

Evaluation Criteria

1. Code Quality (40 points)

Areas to Evaluate:

A. JavaScript/Vue Code Style

• Consistent naming conventions (camelCase, PascalCase, kebab-case used appropriately)
• No unused variables or imports
• Proper use of Vue 3 Composition API (ref, reactive, computed, watch)
• Component size (components should be <300 lines, split if larger)
• Function complexity (max cyclomatic complexity 10)
• Error handling (try/catch blocks, user-friendly error messages)
• Comments (complex logic explained, JSDoc for functions)

Check for:

// BAD: Unused imports
import { ref, reactive, computed, watch, onMounted, onUnmounted } from 'vue'
const name = ref('') // Only ref used

// BAD: No error handling
async function fetchData() {
  const response = await fetch('/api/data')
  return response.json() // What if fetch fails?
}

// BAD: Magic numbers
setTimeout(() => {}, 300000) // What is 300000?

// GOOD
const FIVE_MINUTES_MS = 5 * 60 * 1000
setTimeout(() => {}, FIVE_MINUTES_MS)

B. Backend Code Quality

• Input validation (all user inputs sanitized)
• SQL injection prevention (parameterized queries used everywhere)
• Authentication checks (all protected routes use authenticateToken middleware)
• Consistent error response format
• Proper HTTP status codes (200, 201, 400, 401, 403, 404, 500)
• No hardcoded secrets (API keys in environment variables)

Check for:

// BAD: SQL injection vulnerability
const stmt = db.prepare(`SELECT * FROM users WHERE email = '${email}'`)

// GOOD
const stmt = db.prepare('SELECT * FROM users WHERE email = ?')
stmt.get(email)

// BAD: No input validation
router.post('/api/inventory', async (req, res) => {
  const { boat_id, name } = req.body
  // What if boat_id is null? What if name is 10000 characters?
})

// GOOD
if (!boat_id || typeof boat_id !== 'number') {
  return res.status(400).json({ error: 'boat_id is required and must be a number' })
}
if (!name || name.length > 200) {
  return res.status(400).json({ error: 'name is required and must be <200 chars' })
}

C. Database Schema Quality

• Proper foreign key constraints
• Indexes on frequently queried columns
• Appropriate data types (TEXT vs VARCHAR, INTEGER vs REAL)
• Normalized schema (no redundant data)
• Migration files exist (schema versioning)

Check for:

-- BAD: No foreign key constraint
CREATE TABLE inventory_items (
  id INTEGER PRIMARY KEY,
  boat_id INTEGER, -- What if boat_id references non-existent boat?
  name TEXT
);

-- GOOD
CREATE TABLE inventory_items (
  id INTEGER PRIMARY KEY,
  boat_id INTEGER NOT NULL REFERENCES boats(id) ON DELETE CASCADE,
  name TEXT NOT NULL
);

-- BAD: No index on frequently queried column
SELECT * FROM inventory_items WHERE boat_id = ?; -- Slow if no index

-- GOOD
CREATE INDEX idx_inventory_boat_id ON inventory_items(boat_id);

---

2. Architecture & Design Patterns (20 points)

Areas to Evaluate:

A. Separation of Concerns

• Business logic separated from routes (use service layer)
• Database queries abstracted (use repository pattern or ORM)
• Reusable components (no duplicated code)

Check for:

// BAD: Business logic in route
router.post('/api/expenses', async (req, res) => {
  const db = getDb()
  const { amount, currency } = req.body
  // 50 lines of validation, calculation, and database queries here
})

// GOOD: Service layer
router.post('/api/expenses', async (req, res) => {
  const expense = await ExpenseService.create(req.body)
  res.json(expense)
})

// services/expense.service.js
class ExpenseService {
  static async create(data) {
    // Validation, calculation, database queries
  }
}

B. Component Architecture

• Atomic design (atoms, molecules, organisms)
• Props vs emit usage (proper parent-child communication)
• No prop drilling (use provide/inject or Pinia for deep state)

Check for:

<!-- BAD: Prop drilling (passing data through 3+ levels) -->
<ParentComponent :user="user" />
  <ChildComponent :user="user" />
    <GrandchildComponent :user="user" /> <!-- Antipattern -->

<!-- GOOD: Provide/inject -->
<script setup>
provide('user', user)
</script>

<GrandchildComponent />
<script setup>
const user = inject('user')
</script>

C. State Management

• Global state in Pinia store (not scattered ref() in components)
• Computed properties used (no manual watching)
• Reactive state mutations (no direct array push without triggering reactivity)

---

3. Security (20 points)

OWASP Top 10 Vulnerabilities to Check:

A. SQL Injection

• All database queries use parameterized statements
• No string concatenation in SQL

// CRITICAL VULNERABILITY CHECK
grep -r "db.prepare(\`" server/ # Should return 0 results
grep -r 'db.prepare("' server/ # All should use ? placeholders

B. Cross-Site Scripting (XSS)

• All user input sanitized before rendering
• Vue's default {{ }} escaping used (not v-html on user content)

<!-- BAD: XSS vulnerability -->
<div v-html="userComment"></div> <!-- If userComment contains <script>, it executes -->

<!-- GOOD -->
<div>{{ userComment }}</div> <!-- Escaped automatically -->

C. Authentication & Authorization

• JWT tokens properly validated
• Tokens expire (short lifetime, e.g., 1 hour)
• Refresh token rotation implemented
• Role-based access control (RBAC) for multi-stakeholder access

// CHECK: JWT secret stored securely?
grep -r "JWT_SECRET" server/ # Should NOT find hardcoded secrets

// CHECK: Token expiration
jwt.sign(payload, secret, { expiresIn: '1h' }) // Good
jwt.sign(payload, secret) // BAD: Never expires

D. File Upload Security

• File size limits enforced
• File type validation (not just MIME type, check magic bytes)
• Uploaded files stored outside web root (prevent direct execution)
• Unique filenames (prevent overwriting)

// CHECK: File upload validation
const upload = multer({
  limits: { fileSize: 5 * 1024 * 1024 }, // 5MB ✓
  fileFilter: (req, file, cb) => {
    const allowed = ['image/jpeg', 'image/png']
    if (allowed.includes(file.mimetype)) { // ⚠️ MIME type can be spoofed
      cb(null, true)
    }
  }
})

// BETTER: Check magic bytes
import fileType from 'file-type'
const buffer = await fs.readFile(file.path)
const type = await fileType.fromBuffer(buffer)
if (!['jpg', 'png'].includes(type?.ext)) {
  throw new Error('Invalid file type')
}

E. Secrets Management

• No API keys in code (use .env file)
• .env file in .gitignore
• .env.example provided (template without real secrets)

# CHECK: Are secrets committed?
git log --all --pretty=format: --name-only | grep -i "\.env$"
# Should return 0 results (means .env never committed)

# CHECK: Does .env.example exist?
ls .env.example # Should exist

---

4. Performance Optimization (10 points)

Areas to Evaluate:

A. Frontend Performance

• Code splitting (lazy-loaded routes)
• Bundle size <500KB gzipped
• Image optimization (WebP format, responsive images)
• Debounced search inputs (prevent API spam)
• Virtual scrolling for long lists (>100 items)

Check for:

// BAD: All routes loaded upfront
import HomeView from './views/HomeView.vue'
import DocumentView from './views/DocumentView.vue'

const routes = [
  { path: '/', component: HomeView },
  { path: '/document', component: DocumentView }
]

// GOOD: Lazy loading
const routes = [
  { path: '/', component: () => import('./views/HomeView.vue') },
  { path: '/document', component: () => import('./views/DocumentView.vue') }
]

// CHECK: Bundle size
npm run build
ls -lh dist/assets/*.js # Should be <200KB per chunk

B. Backend Performance

• Database indexes on foreign keys
• Pagination for large datasets (not returning 10,000 rows)
• Response compression (gzip middleware)
• Caching (Redis or in-memory for frequent queries)

// BAD: No pagination (returns all 10,000 items)
router.get('/api/inventory/:boatId', async (req, res) => {
  const items = db.prepare('SELECT * FROM inventory_items WHERE boat_id = ?').all(boatId)
  res.json(items) // Could be 10,000 items
})

// GOOD: Pagination
router.get('/api/inventory/:boatId', async (req, res) => {
  const { limit = 50, offset = 0 } = req.query
  const items = db.prepare(
    'SELECT * FROM inventory_items WHERE boat_id = ? LIMIT ? OFFSET ?'
  ).all(boatId, limit, offset)
  res.json(items)
})

C. Network Optimization

• API responses gzipped
• HTTP/2 enabled (multiplexing)
• CDN for static assets (optional)

---

5. Usability & User Experience (10 points)

Areas to Evaluate:

A. Accessibility (a11y)

• Keyboard navigation (all interactive elements focusable)
• ARIA labels (screen reader support)
• Color contrast ratio ≥4.5:1 (WCAG AA standard)
• Focus indicators visible
• Alt text for images

Check for:

<!-- BAD: No keyboard support -->
<div @click="handleClick">Click me</div>

<!-- GOOD -->
<button @click="handleClick" aria-label="Delete item">
  <TrashIcon />
</button>

<!-- BAD: Low contrast (white text on light blue) -->
<p style="color: #fff; background: #A4C8E1">Text</p> <!-- Contrast ratio 2.1:1 -->

<!-- GOOD: High contrast -->
<p style="color: #fff; background: #1E3A8A">Text</p> <!-- Contrast ratio 8.5:1 -->

B. Error Handling & User Feedback

• Loading states (spinners during API calls)
• Error messages user-friendly (not technical jargon)
• Success confirmations (toasts, not alerts)
• Form validation feedback (inline errors)

<!-- BAD: No loading state -->
<button @click="submitForm">Submit</button>

<!-- GOOD -->
<button @click="submitForm" :disabled="isLoading">
  {{ isLoading ? 'Submitting...' : 'Submit' }}
</button>

<!-- BAD: Technical error -->
<p>Error: SQLITE_CONSTRAINT: UNIQUE constraint failed: users.email</p>

<!-- GOOD: User-friendly -->
<p>This email is already registered. Please try logging in instead.</p>

C. Mobile Responsiveness

• Touch targets ≥44×44px (Apple HIG minimum)
• Responsive breakpoints (desktop, tablet, mobile)
• No horizontal scrolling on mobile
• Mobile-first design (progressive enhancement)

---

Evaluation Instructions

Step 1: Analyze Code Quality (90 minutes)

Run the following commands and analyze output:

cd /home/setup/navidocs

# 1. Check for unused dependencies
npm install -g depcheck
depcheck

# 2. Lint JavaScript/Vue code
npm run lint # (if lint script exists)

# 3. Find hardcoded secrets
grep -r "api_key\|API_KEY\|password\|secret" client/ server/ --exclude-dir=node_modules

# 4. Find SQL injection vulnerabilities
grep -r "db.prepare(\`\${" server/
grep -r 'db.prepare("' server/ | grep -v "?"

# 5. Check bundle size
npm run build
du -sh dist/

# 6. Check database schema
sqlite3 navidocs.db ".schema" > schema.sql
cat schema.sql # Review for missing indexes, foreign keys

# 7. Find components >300 lines
find client/src/components -name "*.vue" -exec wc -l {} \; | awk '$1 > 300 {print $2 " (" $1 " lines)"}'

# 8. Find duplicate code
npm install -g jscpd
jscpd client/src server/

# 9. Analyze complexity
npm install -g complexity-report
cr client/src/**/*.js server/**/*.js

Step 2: Security Audit (60 minutes)

Check for vulnerabilities:

# 1. npm audit
npm audit --production

# 2. Check for exposed secrets in git history
git log --all --pretty=format: --name-only | grep -E "\.env$|credentials|secrets"

# 3. Check authentication middleware usage
grep -r "router.get\|router.post\|router.put\|router.delete" server/routes/ | grep -v "authenticateToken"
# Any routes WITHOUT authenticateToken are publicly accessible

# 4. Check file upload validation
grep -r "multer" server/ -A 10 # Review fileFilter logic

# 5. Check JWT configuration
grep -r "jwt.sign" server/ # Look for expiresIn parameter

Step 3: Architecture Review (60 minutes)

Analyze codebase structure:

# 1. Count lines of code per directory
cloc client/src server/

# 2. Find business logic in routes (antipattern)
find server/routes -name "*.js" -exec wc -l {} \; | awk '$1 > 200 {print}'
# Routes >200 lines likely have business logic mixed in

# 3. Check for service layer
ls server/services/ # Should contain business logic

# 4. Check for state management
grep -r "ref\|reactive" client/src/views/ | wc -l
# If >50 results, state is scattered (should use Pinia)

# 5. Find God components (>500 lines)
find client/src -name "*.vue" -exec wc -l {} \; | awk '$1 > 500 {print}'

Step 4: Performance Analysis (45 minutes)

Measure performance:

# 1. Check for lazy loading
grep -r "import.*from '@/views" client/src/router/
# Should see () => import() syntax

# 2. Find missing pagination
grep -r "\.all(" server/routes/ # Should use .all() sparingly, prefer pagination

# 3. Check for N+1 queries
grep -r "for.*of\|forEach" server/routes/ -A 5 | grep "db.prepare"
# Loop + database query = N+1 problem

# 4. Check for database indexes
sqlite3 navidocs.db "SELECT name FROM sqlite_master WHERE type='index';"
# Should have indexes on foreign keys + frequently queried columns

# 5. Measure bundle size
npm run build
find dist/assets -name "*.js" -exec du -h {} \; | sort -h

Step 5: Generate Comprehensive Report (45 minutes)

Create a markdown report with:

1. Executive Summary (1 paragraph: overall code quality rating 1-10)
2. Critical Issues (bugs that will cause failures)
   • SQL injection vulnerabilities
   • Authentication bypasses
   • Data loss scenarios
3. High Priority Issues (performance, security, UX problems)
   • Missing indexes
   • Large bundle sizes
   • Poor error handling
4. Medium Priority Issues (code quality, maintainability)
   • Duplicated code
   • Complex functions
   • Missing tests
5. Low Priority Issues (nice-to-haves)
   • Inconsistent naming
   • Missing comments
6. Code Quality Metrics
   • Total lines of code
   • Cyclomatic complexity (average)
   • Test coverage % (if tests exist)
   • Bundle size
   • Lighthouse score (if you can run it)
7. Recommended Refactorings (specific code changes with before/after examples)
8. Estimated Effort (hours to fix each category of issues)

---

Output Format

Generate a file: /home/setup/navidocs/CODEX_REVIEW_REPORT.md

Structure:

# NaviDocs Code Review - Codex GPT-5 High

**Reviewed:** 2025-11-14
**Codebase Version:** navidocs-cloud-coordination branch
**Reviewer:** Codex GPT-5 High
**Overall Rating:** 7.5/10 (Good, with room for improvement)

---

## Executive Summary

[1 paragraph summary]

---

## Critical Issues (Must Fix Before Launch) 🔴

### 1. SQL Injection Vulnerability in Maintenance Routes
**File:** `server/routes/maintenance.js:145`
**Issue:**
```javascript
// VULNERABLE CODE
const stmt = db.prepare(`SELECT * FROM maintenance WHERE id = ${id}`)

Fix:

// FIXED CODE
const stmt = db.prepare('SELECT * FROM maintenance WHERE id = ?')
stmt.get(id)

Impact: Allows attackers to execute arbitrary SQL, steal data, or delete database Effort: 5 minutes

---

[Continue for all issues...]

---

Code Quality Metrics

Metric	Value	Target	Status
Total LoC	24,178	N/A	✅
Avg Complexity	8.3	<10	✅
Bundle Size	487 KB	<500 KB	✅
Test Coverage	0%	>80%	❌
npm audit issues	3 moderate	0	⚠️
Lighthouse (mobile)	72	>90	❌

---

Recommended Refactorings

1. Extract Business Logic to Service Layer

Current (Antipattern):

// server/routes/expenses.js (189 lines)
router.post('/api/expenses', async (req, res) => {
  // 150 lines of validation, calculation, database queries
})

Refactored:

// server/routes/expenses.js (10 lines)
router.post('/api/expenses', async (req, res) => {
  const expense = await ExpenseService.create(req.body, req.user)
  res.json(expense)
})

// server/services/expense.service.js (new file)
class ExpenseService {
  static async create(data, user) {
    this.validate(data)
    const splits = this.calculateSplits(data)
    return this.save(data, splits, user)
  }
}

Effort: 4 hours (refactor all 5 route files)

---

[Continue for all recommendations...]

---

Total Effort Estimate

Priority	Issues	Estimated Hours
Critical	3	2 hours
High	12	16 hours
Medium	24	32 hours
Low	18	12 hours
Total	57	62 hours

Budget: €4,960 at €80/hr

---

Conclusion

[Final thoughts, overall recommendations]

---

## Additional Analysis (If Time Permits)

### **A. Run Automated Tests (If Test Suite Exists)**
```bash
npm test
npm run test:e2e

B. Run Lighthouse Audit

npm install -g lighthouse
lighthouse http://localhost:3200 --output html --output-path lighthouse-report.html
# Check for:
# - Performance score >90
# - Accessibility score >90
# - Best practices score >90
# - SEO score >90

C. Analyze Dependencies

npm list --depth=0 # Check for outdated packages
npm outdated # Check for security updates

D. Check for TODO/FIXME Comments

grep -r "TODO\|FIXME\|HACK\|XXX" client/ server/ --exclude-dir=node_modules

---

Special Focus Areas (NaviDocs-Specific)

Based on the stakeholder requirements and UI research, pay special attention to:

1. Multi-Stakeholder Access Control

   • Check if role-based permissions are implemented
   • Verify captain can't delete owner's documents
   • Verify crew can only see assigned tasks

2. Camera Integration

   • Check RTSP URL validation (prevent SSRF attacks)
   • Verify camera snapshots are cached (not fetched on every page load)
   • Check for proper error handling when camera offline

3. Weather Module

   • Check if weather data is cached (don't hit API every page load)
   • Verify graceful degradation when offline
   • Check for proper error handling when API fails

4. File Upload Security

   • Verify photo uploads are validated (file type, size)
   • Check filenames are sanitized (prevent path traversal)
   • Verify uploads are stored outside web root

5. Mobile Responsiveness

   • Check touch targets ≥60×60px (for glove operation on yachts)
   • Verify high contrast (for sunlight readability)
   • Check glass morphism performance (backdrop-filter can be slow)

---

Good Luck!

Your review will be invaluable for improving NaviDocs code quality, security, and usability. Focus on providing actionable recommendations with specific code examples and realistic effort estimates.

Remember: The goal is not to criticize, but to help build a production-ready boat management platform that yacht owners love.