OpenNoodl/dev-docs/tasks/phase-1/TASK-002-legacy-project-migration/NOTES.md

TASK-002 Working Notes: Legacy Project Migration

Research Findings

Project File Structure

Document findings about Noodl project structure here

TODO: Analyze sample .noodl project folders

Expected structure (to be verified):
my-project/
├── project.json          # Project metadata
├── components/           # Component definitions
│   └── component-name/
│       └── component.json
├── pages/                # Page definitions
├── styles/               # Style definitions
└── assets/               # Project assets (if any)

Known Version Indicators

Document where version information is stored

TODO: Check these locations for version metadata:

• project.json root object
• File header comments
• Metadata fields in component files
• Any .noodl-version or similar files

Node Definition Changes

Track changes to node definitions across versions

Node Type	Old API	New API	Version Changed
TBD	TBD	TBD	TBD

---

Breaking Changes Map

From TASK-001 Dependency Updates

React 17 → 19

Change	Impact on Projects	Migration Strategy
ReactDOM.render() deprecated	May affect stored render patterns	TBD
New Suspense behavior	May affect loading states	TBD
Concurrent features	May affect event handling	TBD

react-instantsearch-hooks-web → react-instantsearch

Change	Impact on Projects	Migration Strategy
Package rename	Import paths	N/A (editor code only)
API changes	TBD	TBD

Other Dependencies

Add findings here as TASK-001 progresses

---

Design Decisions

Migration Engine Architecture

Decision: [TBD] Alternatives Considered:

1. Option A: ...
2. Option B: ... Rationale: ...

Backup Strategy

Decision: [TBD] Options:

1. In-place backup (.backup folder in project)
2. External backup location (user-configurable)
3. Timestamped copies Rationale: ...

CLI Tool Location

Decision: [TBD] Options:

1. New packages/noodl-cli/ package
2. Add to existing packages/noodl-platform-node/
3. Scripts in scripts/ directory Rationale: ...

---

Questions & Answers

Q: Where is project version stored?

A: [TBD - needs research]

Q: What's the oldest supported Noodl version?

A: [TBD - needs community input]

Q: Do we have sample legacy projects for testing?

A: [TBD - need to source these]

Q: Should migration be automatic or opt-in?

A: [TBD - needs UX decision]

---

Gotchas & Surprises

Document unexpected discoveries here

[Discovery 1]

• Date: TBD
• Finding: ...
• Impact: ...
• Resolution: ...

---

Debug Log

Research Phase

[Date/Time] - Starting project format analysis
- Trying: ...
- Result: ...
- Next: ...

---

Useful References

Codebase Locations

# Project loading code
packages/noodl-editor/src/editor/src/models/projectmodel.js

# Node definitions
packages/noodl-runtime/src/nodes/

# Runtime context
packages/noodl-runtime/src/nodecontext.js

# Viewer React components
packages/noodl-viewer-react/src/nodes/

Search Commands

# Find project loading logic
grep -r "loadProject\|openProject" packages/noodl-editor/ --include="*.ts" --include="*.js"

# Find version references
grep -r "version" packages/noodl-editor/src/editor/src/models/ --include="*.ts" --include="*.js"

# Find serialization logic
grep -r "serialize\|deserialize\|toJSON\|fromJSON" packages/ --include="*.ts" --include="*.js"

External Documentation

• React 19 Migration: https://react.dev/blog/2024/04/25/react-19
• react-instantsearch v7: https://www.algolia.com/doc/guides/building-search-ui/upgrade-guides/react/

---

Community Feedback

Collect feedback from Noodl users about migration concerns

User Concerns

1. [TBD]

User Requests

1. [TBD]

Known Legacy Projects in the Wild

1. [TBD - need to identify common project patterns]

---

Test Project Inventory

Name	Version	Complexity	Contains	Location
TBD	TBD	TBD	TBD	TBD

---

Migration Algorithm Pseudocode

function migrateProject(projectPath):
    1. detectVersion(projectPath)
    2. if currentVersion >= targetVersion:
        return SUCCESS (no migration needed)
    3. migrationPath = calculateMigrationPath(currentVersion, targetVersion)
    4. if migrationPath.length == 0:
        return ERROR (no migration path)
    5. backup = createBackup(projectPath)
    6. for migration in migrationPath:
        result = migration.execute(projectPath)
        if result.failed:
            restoreBackup(backup)
            return ERROR (migration failed)
        updateVersionMetadata(projectPath, migration.toVersion)
    7. validate(projectPath)
    8. return SUCCESS

---

Open Items

• Get access to legacy Noodl projects for testing
• Confirm oldest version we need to support
• Determine if cloud configurations need migration
• Design migration dialog UX
• Decide on CLI package location and build strategy