OpenNoodl/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-001B-launcher-fixes/INVESTIGATE-routing-error.md

Investigation Guide: Dashboard Routing Error

Issue Reference: ISSUE-routing-error.md
Error: ERR_FILE_NOT_FOUND for file:///dashboard/projects
Discovered: 2026-01-07

---

Quick Summary

The Electron app fails to load the dashboard route with ERR_FILE_NOT_FOUND. This investigation guide provides a systematic approach to diagnose and fix the issue.

---

Step 1: Verify the Error

Reproduce the Issue

# Clean everything first
npm run clean:all

# Start dev server
npm run dev

# Observe error in terminal:
# Editor: (node:XXXXX) electron: Failed to load URL: file:///dashboard/projects with error: ERR_FILE_NOT_FOUND

Check Console

1. Open DevTools in Electron app (View → Toggle Developer Tools)
2. Look for errors in Console tab
3. Look for failed network requests in Network tab
4. Note exact error messages and stack traces

---

Step 2: Understand the Architecture

Electron Main Process vs Renderer Process

Main Process (packages/noodl-editor/src/main/):

• Handles window creation
• Registers protocol handlers
• Manages file:// URL loading
• Sets up IPC communication

Renderer Process (packages/noodl-editor/src/editor/):

• Runs React app
• Handles routing (React Router or similar)
• Communicates with main via IPC

Current Architecture (Post-TASK-001B)

TASK-001B made these changes:

1. Electron Store Migration - Projects stored in Electron's storage
2. Service Integration - New ProjectOrganizationService
3. Remove List View - Simplified launcher UI
4. Create Project Modal - New modal-based creation

---

Step 3: Check Route Configuration

A. React Router Configuration

File to check: packages/noodl-editor/src/editor/src/router.tsx (or similar)

// Look for route definitions
<Route path="/dashboard/projects" component={ProjectsPage} />

// Check if route was renamed or removed
<Route path="/launcher" component={Launcher} />
<Route path="/projects" component={ProjectsPage} />

What to verify:

• Does the /dashboard/projects route exist?
• Was it renamed to something else?
• Is there a redirect from old to new route?

B. Electron Protocol Handler

File to check: packages/noodl-editor/src/main/ (main process files)

// Look for protocol registration
protocol.registerFileProtocol('file', (request, callback) => {
  const url = request.url.substr(7); // Remove 'file://'
  callback({ path: path.normalize(`${__dirname}/${url}`) });
});

What to verify:

• Is file:// protocol properly registered?
• Does the path resolution work correctly?
• Are paths correctly normalized?

C. Window Loading

File to check: Main window creation code

// Check how the window loads the initial URL
mainWindow.loadURL('file:///' + path.join(__dirname, 'index.html'));

// Or for dev mode
mainWindow.loadURL('http://localhost:3000/dashboard/projects');

What to verify:

• Is it using file:// or http:// in dev mode?
• Is webpack dev server running on the expected port?
• Is the initial route correct?

---

Step 4: Compare Before/After TASK-001B

Files Changed in TASK-001B

Review these files for routing-related changes:

# Check git history for TASK-001B changes
git log --oneline --grep="TASK-001B" --all

# Or check recent commits
git log --oneline -20

# Compare specific files
git diff <commit-before-001B> <commit-after-001B> packages/noodl-editor/src/editor/src/router.tsx
git diff <commit-before-001B> <commit-after-001B> packages/noodl-editor/src/main/

Key Questions

1. Was the dashboard route path changed?

   • From: /dashboard/projects
   • To: /launcher, /projects, or something else?

2. Was the launcher moved?

   • Previously: Separate route
   • Now: Modal or embedded component?

3. Was the initial route changed?

   • Check where the app navigates on startup

---

Step 5: Check Webpack Dev Server Configuration

Development Server Setup

File to check: packages/noodl-editor/webpackconfigs/editor.dev.config.js

devServer: {
  contentBase: path.join(__dirname, '../build'),
  port: 3000,
  historyApiFallback: {
    // Important for SPA routing
    rewrites: [
      { from: /^\/dashboard\/.*/, to: '/index.html' },
    ]
  }
}

What to verify:

• Is historyApiFallback configured?
• Are the route patterns correct?
• Is the dev server actually running?

Check if Dev Server is Running

# While npm run dev is running, check in terminal
# Look for: "webpack-dev-server is listening on port 3000"

# Or check manually
curl http://localhost:3000/dashboard/projects
# Should return HTML, not 404

---

Step 6: Check Electron Build Configuration

Electron Main Entry Point

File to check: packages/noodl-editor/package.json

{
  "main": "src/main/index.js",
  "scripts": {
    "dev": "..."
  }
}

What to verify:

• Is the main entry point correct?
• Does the dev script properly start both webpack-dev-server AND Electron?

Development Mode Detection

File to check: Main process initialization

const isDev = process.env.NODE_ENV === 'development';

if (isDev) {
  mainWindow.loadURL('http://localhost:3000/dashboard/projects');
} else {
  mainWindow.loadURL('file://' + path.join(__dirname, 'index.html'));
}

What to verify:

• Is dev mode correctly detected?
• Is it trying to load from webpack dev server or file://?
• If using file://, does the file exist?

---

Step 7: Check Project Storage Changes

LocalStorage to Electron Store Migration

TASK-001B migrated from localStorage to Electron's storage. Check if this affects routing:

File to check: packages/noodl-editor/src/editor/src/services/ProjectOrganizationService.ts

// Check if service initialization affects routing
export class ProjectOrganizationService {
  constructor() {
    // Does this redirect to a different route?
    // Does this check for existing projects and navigate accordingly?
  }
}

What to verify:

• Does the service redirect on initialization?
• Is there navigation logic based on stored projects?
• Could empty storage cause a routing error?

---

Step 8: Test Potential Fixes

Fix 1: Update Route References

If the route was renamed:

// In main process or router
// OLD:
mainWindow.loadURL('http://localhost:3000/dashboard/projects');

// NEW:
mainWindow.loadURL('http://localhost:3000/launcher'); // or '/projects'

Fix 2: Add Route Redirect

If maintaining backward compatibility:

// In router.tsx
<Redirect from="/dashboard/projects" to="/launcher" />

Fix 3: Fix Webpack Dev Server

If historyApiFallback is misconfigured:

// In webpack config
historyApiFallback: {
  index: '/index.html',
  disableDotRule: true,
  rewrites: [
    { from: /./, to: '/index.html' } // Catch all
  ]
}

Fix 4: Fix Protocol Handler

If file:// protocol is broken:

// In main process
protocol.interceptFileProtocol('file', (request, callback) => {
  const url = request.url.substr(7);
  callback({ path: path.normalize(`${__dirname}/${url}`) });
});

---

Step 9: Verify the Fix

After applying a fix:

# Clean and restart
npm run clean:all
npm run dev

# Verify:
# 1. No errors in terminal
# 2. Dashboard/launcher loads correctly
# 3. DevTools console has no errors
# 4. Can create/open projects

Test Cases

1. ✅ App launches without errors
2. ✅ Dashboard/projects list appears
3. ✅ Can create new project
4. ✅ Can open existing project
5. ✅ Navigation between routes works
6. ✅ Reload (Cmd+R / Ctrl+R) doesn't break routing

---

Step 10: Document the Solution

Once fixed, update:

1. ISSUE-routing-error.md - Add resolution section
2. CHANGELOG - Document what was changed
3. LEARNINGS.md - Add entry if it's a gotcha others might hit

Example Resolution Entry

## Resolution (2026-01-XX)

**Root Cause**: The route was renamed from `/dashboard/projects` to `/launcher` in TASK-001B but the Electron main process was still trying to load the old route.

**Fix Applied**: Updated main process to load `/launcher` instead of `/dashboard/projects`.

**Files Modified**:

- `packages/noodl-editor/src/main/index.js` (line 42)

**Verification**: App now loads correctly in dev mode.

---

Common Scenarios & Solutions

Scenario 1: Route was Renamed

Symptoms:

• Error: ERR_FILE_NOT_FOUND
• Old route reference in main process

Solution:

• Find where the route is loaded in main process
• Update to new route name
• Add redirect for backward compatibility

Scenario 2: Dev Server Not Running

Symptoms:

• Error: ERR_CONNECTION_REFUSED or ERR_FILE_NOT_FOUND
• Port 3000 not responding

Solution:

• Check if npm run dev starts webpack-dev-server
• Check package.json scripts
• Verify port isn't already in use

Scenario 3: Webpack Config Issue

Symptoms:

• 404 on route navigation
• Dev server runs but routes return 404

Solution:

• Add/fix historyApiFallback in webpack config
• Ensure all SPA routes fall back to index.html

Scenario 4: Electron Protocol Handler Broken

Symptoms:

• Production build also fails
• File:// URLs don't resolve

Solution:

• Review protocol handler registration
• Check path normalization logic
• Verify __dirname points to correct location

---

Additional Resources

• Electron Protocol Documentation: https://www.electronjs.org/docs/latest/api/protocol
• Webpack DevServer: https://webpack.js.org/configuration/dev-server/
• React Router: https://reactrouter.com/

---

Quick Debugging Checklist

• Reproduced the error
• Checked console for additional errors
• Verified route exists in router configuration
• Checked if route was renamed in TASK-001B
• Verified webpack dev server is running
• Checked main process window.loadURL call
• Reviewed historyApiFallback configuration
• Tested with clean build
• Verified fix works after reload
• Documented the solution

---

Remember: The goal is to understand WHY the route fails, not just make it work. Document your findings for future reference.