OpenNoodl/dev-docs/tasks/phase-0-foundation-stabilisation/TASK-010-project-creation-bug-fix

TASK-010: Critical Bug - Project Creation Fails Due to Incomplete JSON Structure

Status: ✅ COMPLETED
Priority: URGENT (P0 - Blocker)
Complexity: Medium
Estimated Effort: 1 day
Actual Effort: ~1 hour
Completed: January 9, 2026

Problem Statement

Users cannot create new projects - a critical blocker that has occurred repeatedly despite multiple fix attempts. The issue manifests with the error:

TypeError: Cannot read properties of undefined (reading 'comments')
    at NodeGraphModel.fromJSON (NodeGraphModel.ts:57:1)
    at ComponentModel.fromJSON (componentmodel.ts:44:1)
    at ProjectModel.fromJSON (projectmodel.ts:165:1)

Impact

• Severity: P0 - Blocks all new users
• Affected Users: Anyone trying to create a new project
• Workaround: None available
• User Frustration: HIGH ("ça commence à être vraiment agaçant!")

History of Failed Attempts

Attempt 1: LocalTemplateProvider with relative paths (January 8, 2026)

Issue: Path resolution failed with __dirname in webpack bundles

Error: Hello World template not found at: ./project-examples/version 1.1.0/template-project

Attempt 2: LocalTemplateProvider with process.cwd() (January 8, 2026)

Issue: process.cwd() pointed to wrong directory

Error: Hello World template not found at: /Users/tw/dev/OpenNoodl/OpenNoodl/packages/noodl-editor/project-examples/...

Attempt 3: Programmatic project creation (January 8, 2026)

Issue: Incomplete JSON structure missing required fields

const minimalProject = {
  name: name,
  components: [
    {
      name: 'App',
      ports: [],
      visual: true,
      visualStateTransitions: [],
      nodes: [
        /* ... */
      ]
    }
  ],
  settings: {},
  metadata: {
    /* ... */
  }
};

Error: Cannot read properties of undefined (reading 'comments')

This indicates the structure is missing critical fields expected by NodeGraphModel.fromJSON().

Root Causes

1. Incomplete understanding of project.json schema

   • No formal schema documentation
   • Required fields not documented
   • Nested structure requirements unclear

2. Missing graph/node metadata

   • comments field expected but not provided
   • Possibly other required fields: connections, roots, graph, etc.

3. No validation before project creation

   • Projects created without structure validation
   • Errors only caught during loading
   • No helpful error messages about missing fields

Required Investigation

1. Analyze Complete Project Structure

• Find and analyze a working project.json
• Document ALL required fields at each level
• Identify which fields are truly required vs optional
• Document field types and default values

2. Analyze NodeGraphModel.fromJSON

• Find the actual fromJSON implementation
• Document what fields it expects
• Understand the comments field requirement
• Check for other hidden dependencies

3. Analyze ComponentModel.fromJSON

• Document the component structure requirements
• Understand visual vs non-visual components
• Document the graph/nodes relationship

Proposed Solution

Option A: Use Existing Template (RECOMMENDED)

Instead of creating from scratch, use the actual template project:

// 1. Bundle template-project as a static asset
// 2. Copy it properly during build
// 3. Reference it correctly at runtime

const templateAsset = require('../../../assets/templates/hello-world/project.json');
const project = JSON.parse(JSON.stringify(templateAsset)); // Deep clone
project.name = projectName;
// Write to disk

Pros:

• Uses validated structure
• Guaranteed to work
• Easy to maintain
• Can add more templates later

Cons:

• Requires webpack configuration
• Larger bundle size

Option B: Complete Programmatic Structure

Document and implement the full structure:

const completeProject = {
  name: name,
  components: [
    {
      name: 'App',
      ports: [],
      visual: true,
      visualStateTransitions: [],
      graph: {
        roots: [
          /* root node ID */
        ],
        comments: [], // REQUIRED!
        connections: []
      },
      nodes: [
        {
          id: guid(),
          type: 'Group',
          x: 0,
          y: 0,
          parameters: {},
          ports: [],
          children: [
            /* ... */
          ]
        }
      ]
    }
  ],
  settings: {},
  metadata: {
    title: name,
    description: 'A new Noodl project'
  },
  // Other potentially required fields
  version: '1.1.0',
  variants: []
  // ... etc
};

Pros:

• No external dependencies
• Smaller bundle
• Full control

Cons:

• Complex to maintain
• Easy to miss required fields
• Will break with schema changes

Implementation Plan

Phase 1: Investigation (2-3 hours)

• Find a working project.json file
• Document its complete structure
• Find NodeGraphModel/ComponentModel fromJSON implementations
• Document all required fields
• Create schema documentation

Phase 2: Quick Fix (1 hour)

• Implement Option A (use template as asset)
• Configure webpack to bundle template
• Update LocalProjectsModel to use bundled template
• Test project creation
• Verify project opens correctly

Phase 3: Validation (1 hour)

• Add project JSON schema validation
• Validate before writing to disk
• Provide helpful error messages
• Add unit tests for project creation

Phase 4: Documentation (1 hour)

• Document project.json schema
• Add examples of minimal valid projects
• Document how to create custom templates
• Update LEARNINGS.md with findings

Files to Modify

Investigation

• Find: NodeGraphModel (likely in packages/noodl-editor/src/editor/src/models/)
• Find: ComponentModel (same location)
• Find: Valid project.json (check existing projects or tests)

Implementation

• packages/noodl-editor/src/editor/src/utils/LocalProjectsModel.ts
  • Fix project creation logic
• packages/noodl-editor/webpackconfigs/webpack.renderer.dev.js
  • Add template asset bundling if needed
• packages/noodl-editor/src/editor/src/models/projectmodel.ts
  • Add validation logic

Documentation

• dev-docs/reference/PROJECT-JSON-SCHEMA.md (NEW)
• dev-docs/reference/LEARNINGS.md
• dev-docs/reference/COMMON-ISSUES.md

Testing Strategy

Manual Tests

• Create new project from dashboard
• Verify project opens without errors
• Verify "App" component is visible
• Verify nodes are editable
• Verify project saves correctly
• Close and reopen project

Regression Tests

• Test with existing projects
• Test with template-based projects
• Test empty project creation
• Test project import

Unit Tests

• Test project JSON generation
• Test JSON validation
• Test error handling

Success Criteria

• New users can create projects successfully
• No console errors during project creation
• Projects load correctly after creation
• All components are visible in the editor
• Projects can be saved and reopened
• Solution works in both dev and production
• Comprehensive documentation exists
• Tests prevent regression

Related Issues

• Original bug report: Console error "Cannot read properties of undefined (reading 'comments')"
• Related to TASK-009-template-system-refactoring (future enhancement)
• Impacts user onboarding and first-time experience

Post-Fix Actions

1. Update TASK-009: Reference this fix as prerequisite
2. Add to LEARNINGS.md: Document the project.json schema learnings
3. Add to COMMON-ISSUES.md: Document this problem and solution
4. Create schema documentation: Formal PROJECT-JSON-SCHEMA.md
5. Add validation: Prevent future similar issues

Notes

• This is the THIRD attempt to fix this issue
• Problem is recurring due to lack of understanding of required schema
• Proper investigation and documentation needed this time
• Must validate before considering complete

---

Created: January 9, 2026
Last Updated: January 9, 2026
Assignee: TBD
Blocked By: None
Blocks: User onboarding, TASK-009