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:**
```javascript
// 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:**
```javascript
// 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:**
```sql
-- 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:**
```javascript
// 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:**
```vue
<!-- 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

```javascript
// 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)

```vue
<!-- 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

```javascript
// 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)

```javascript
// 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)

```bash
# 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:**
```javascript
// 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)

```javascript
// 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:**
```vue
<!-- 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)

```vue
<!-- 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:**

```bash
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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```markdown
# 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:**
```javascript
// 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):**
```javascript
// server/routes/expenses.js (189 lines)
router.post('/api/expenses', async (req, res) => {
  // 150 lines of validation, calculation, database queries
})
```

**Refactored:**
```javascript
// 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**
```bash
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**
```bash
npm list --depth=0 # Check for outdated packages
npm outdated # Check for security updates
```

### **D. Check for TODO/FIXME Comments**
```bash
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.