OpenNoodl/dev-docs/tasks/phase-5-multi-target-deployment/01-byob-backend/TASK-007-integrated-backend/CHECKLIST.md

TASK-007: Integrated Local Backend - Implementation Checklist

Pre-Implementation

• Review existing CloudStore implementation (packages/noodl-runtime/src/api/cloudstore.js)
• Review existing CloudRunner implementation (packages/noodl-viewer-cloud/src/)
• Review existing cloud-function-server (packages/noodl-editor/src/main/src/cloud-function-server.js)
• Create feature branch: feature/007-integrated-local-backend
• Set up development environment with SQLite tools

---

Phase A: Foundation - LocalSQL Adapter (16-20 hours)

A.1: SQLite Integration (4 hours)

• Install better-sqlite3 dependency in noodl-runtime
• Create adapter directory structure:

  packages/noodl-runtime/src/api/adapters/
  ├── index.ts
  ├── cloudstore-adapter.ts
  └── local-sql/
      ├── LocalSQLAdapter.ts
      ├── SQLiteConnection.ts
      ├── QueryBuilder.ts
      ├── SchemaManager.ts
      └── types.ts
  

• Define CloudStoreAdapter interface with all required methods
• Implement SQLiteConnection wrapper class
• Implement basic LocalSQLAdapter constructor and connection
• Add WAL mode pragma for better concurrency
• Test: Database file creation and basic connection

A.2: Query Translation (4 hours)

• Implement QueryBuilder.buildSelect() for basic queries
• Implement WHERE clause translation for operators:
  • equalTo / notEqualTo
  • greaterThan / lessThan / greaterThanOrEqualTo / lessThanOrEqualTo
  • containedIn / notContainedIn
  • exists
  • contains / startsWith / endsWith
  • regex (via GLOB)
• Implement ORDER BY clause translation
• Implement LIMIT/OFFSET translation
• Implement QueryBuilder.buildInsert()
• Implement QueryBuilder.buildUpdate()
• Implement QueryBuilder.buildDelete()
• Test: Complex queries with multiple operators
• Test: Query performance with 10,000+ records

A.3: Schema Management (4 hours)

• Define TableSchema and ColumnDefinition interfaces
• Implement SchemaManager.createTable()
• Map Noodl types to SQLite types:
  • String → TEXT
  • Number → REAL
  • Boolean → INTEGER (0/1)
  • Date → TEXT (ISO8601)
  • Object/Array → TEXT (JSON)
  • Pointer → TEXT (objectId reference)
  • Relation → Junction table
• Implement SchemaManager.addColumn()
• Implement SchemaManager.exportSchema()
• Implement SchemaManager.generatePostgresSQL()
• Implement SchemaManager.generateSupabaseSQL()
• Create automatic indexes for createdAt, updatedAt
• Test: Schema creation and migration
• Test: Export to PostgreSQL format

A.4: Adapter Registration & Selection (4 hours)

• Create AdapterRegistry singleton class
• Implement createAdapter() factory method
• Refactor existing CloudStore to use adapter pattern
• Create ParseAdapter wrapper around existing code
• Implement adapter switching based on project config
• Add adapter lifecycle methods (connect/disconnect)
• Test: Adapter switching between local and Parse
• Test: Multiple simultaneous adapters

Phase A Verification

• All query operators work correctly
• Schema creation handles all Noodl data types
• Export generates valid PostgreSQL SQL
• No regressions in Parse adapter functionality
• Performance benchmarks documented

---

Phase B: Local Backend Server (12-16 hours)

B.1: Server Architecture (4 hours)

• Create local-backend directory in noodl-editor/src/main/src/
• Implement LocalBackendServer class
• Set up Express middleware (CORS, JSON parsing)
• Implement REST routes:
  • GET /health - Health check
  • GET /api/_schema - Get schema
  • POST /api/_schema - Update schema
  • GET /api/_export - Export data
  • GET /api/:table - Query records
  • GET /api/:table/:id - Fetch single record
  • POST /api/:table - Create record
  • PUT /api/:table/:id - Update record
  • DELETE /api/:table/:id - Delete record
  • POST /functions/:name - Execute workflow
  • POST /api/_batch - Batch operations
• Test: All REST endpoints with curl/Postman

B.2: WebSocket Realtime (3 hours)

• Add ws dependency
• Implement WebSocket server on same HTTP server
• Implement client subscription tracking
• Implement broadcast() method for events
• Wire adapter events to WebSocket broadcast
• Handle client disconnection cleanup
• Test: Subscribe and receive realtime updates
• Test: Multiple clients receive broadcasts

B.3: Backend Manager (4 hours)

• Create BackendManager singleton class
• Implement backend storage structure:

  ~/.noodl/backends/{id}/
  ├── config.json
  ├── schema.json
  ├── workflows/
  └── data/local.db
  

• Implement IPC handlers:
  • backend:list - List all backends
  • backend:create - Create new backend
  • backend:delete - Delete backend
  • backend:start - Start backend server
  • backend:stop - Stop backend server
  • backend:status - Get backend status
  • backend:export-schema - Export schema
  • backend:export-data - Export data
• Implement automatic port allocation
• Wire BackendManager into main process
• Test: Create/start/stop backend from IPC

B.4: Editor Integration (3 hours)

• Create BackendModel in editor
• Implement loadProjectBackend() method
• Add backend status to project model
• Create backend indicator in editor header
• Implement start/stop controls in UI
• Test: Backend starts with project if autoStart enabled
• Test: Backend stops when project closes

Phase B Verification

• Backend server starts and responds to requests
• Realtime WebSocket updates work
• Multiple backends can run simultaneously
• IPC commands work from renderer process
• Editor shows correct backend status

---

Phase C: Visual Workflow Runtime (12-16 hours)

C.1: Runtime Adaptation (4 hours)

• Review existing CloudRunner implementation
• Modify CloudRunner to accept local adapter
• Remove Parse-specific dependencies from base runtime
• Add adapter injection to runtime context
• Ensure sandbox.isolate.js works in pure Node.js
• Test: CloudRunner executes workflows with local adapter

C.2: Database Nodes (4 hours)

• Create noodl.local.query node
• Create noodl.local.insert node
• Create noodl.local.update node
• Create noodl.local.delete node
• Create noodl.local.transaction node (optional)
• Add nodes to cloud viewer node registry
• Test: Each node type in isolation
• Test: Nodes work in visual workflow

C.3: Trigger Nodes (4 hours)

• Create noodl.trigger.schedule node (cron-based)
• Create noodl.trigger.dbChange node
• Create noodl.trigger.webhook node
• Implement trigger registration system
• Implement trigger cleanup on node deletion
• Test: Schedule triggers at specified intervals
• Test: DB change triggers fire correctly
• Test: Webhook triggers receive HTTP requests

C.4: Workflow Hot Reload (4 hours)

• Create WorkflowCompiler class
• Implement debounced compilation on component change
• Export workflows to backend workflows directory
• Implement backend:update-workflow IPC handler
• Implement backend:reload-workflows IPC handler
• Test: Workflow changes reflect immediately
• Test: No service interruption during reload

Phase C Verification

• CloudRunner executes workflows with local database
• All database node types work correctly
• All trigger types fire at appropriate times
• Hot reload works without restarting backend
• No memory leaks in long-running workflows

---

Phase D: Launcher Integration (8-10 hours)

D.1: Backend List UI (3 hours)

• Create BackendManager directory in Launcher views
• Create BackendList.tsx component
• Create BackendCard.tsx component
• Implement backend loading from IPC
• Implement status indicators (running/stopped)
• Add start/stop controls per backend
• Add delete button with confirmation
• Test: List displays all backends correctly

D.2: Create Backend UI (2 hours)

• Create CreateBackendDialog.tsx component
• Implement name input with validation
• Call backend:create on confirmation
• Refresh list after creation
• Test: New backend appears in list

D.3: Backend Selector (3 hours)

• Create BackendSelector.tsx dropdown component
• Show in project card when editing settings
• Implement backend association saving
• Update project config on selection
• Option to create new backend from selector
• Test: Backend association persists
• Test: Switching backends works correctly

D.4: Backend Admin Panel (2 hours)

• Create basic data viewer component
• Show tables and record counts
• Allow basic CRUD operations
• Show recent activity/logs
• Test: Data displays correctly
• Test: CRUD operations work

Phase D Verification

• Launcher shows all backends with status
• Can create/delete backends from launcher
• Can start/stop backends independently
• Projects can be associated with backends
• Basic data administration works

---

Phase E: Migration & Export (8-10 hours)

E.1: Schema Export Wizard (4 hours)

• Create ExportWizard.tsx component
• Implement format selection (Postgres, Supabase, PocketBase, JSON)
• Implement include data option
• Generate export via IPC
• Display result in code viewer
• Implement copy to clipboard
• Implement download as file
• Test: Each export format generates valid output

E.2: Parse Migration Wizard (4 hours)

• Create ParseMigrationWizard.tsx component
• Implement Parse schema fetching
• Display schema review with record counts
• Implement migration progress UI
• Create local backend during migration
• Import schema structure
• Import data in batches
• Handle migration errors gracefully
• Test: Full migration from Parse to local

E.3: External Migration Guide (2 hours)

• Create migration documentation
• Document Supabase migration steps
• Document PocketBase migration steps
• Add links from export wizard
• Test: Following guide successfully migrates

Phase E Verification

• Schema exports to all target formats
• Parse migration preserves all data
• Migration can be cancelled/resumed
• Export documentation is complete

---

Phase F: Standalone Deployment (8-10 hours)

F.1: Backend Bundler (4 hours)

• Create backend-bundler.ts utility
• Pre-compile server bundle for Node.js
• Pre-compile server bundle for Electron
• Implement schema copying
• Implement workflows copying
• Implement optional data copying
• Generate package.json for standalone
• Generate startup script
• Test: Bundled backend runs standalone

F.2: Electron Deployment Integration (4 hours)

• Modify Electron deployer to support backend
• Add "Include Backend" option to deploy wizard
• Add "Include Data" sub-option
• Integrate backend bundle into Electron package
• Modify Electron main.js to start backend
• Handle backend cleanup on app quit
• Test: Electron app with embedded backend works
• Test: App starts backend on launch

F.3: Documentation (2 hours)

• Document standalone deployment process
• Document backend configuration options
• Document production considerations
• Add troubleshooting guide
• Test: Follow docs to deploy successfully

Phase F Verification

• Backend can be bundled for standalone use
• Electron apps include working backend
• Deployed apps work offline
• Documentation covers all scenarios

---

Final Verification

Functional Testing

• New user can create backend with zero configuration
• Visual workflows execute correctly in local backend
• Realtime updates work via WebSocket
• All database operations work correctly
• All trigger types fire correctly
• Schema export produces valid output
• Parse migration preserves data
• Electron deployment works with backend

Backward Compatibility

• Existing Parse projects load without errors
• Parse adapter functions correctly
• Can switch from Parse to local backend
• No regressions in existing functionality

Performance

• Query performance acceptable with 100K records
• WebSocket can handle 100 simultaneous clients
• Hot reload completes within 1 second
• Memory usage stable over time

Documentation

• README covers all features
• API documentation complete
• Migration guides complete
• Troubleshooting guide complete

---

Post-Implementation

• Update main phase documentation with completion status
• Create PR with comprehensive description
• Request code review
• Address review feedback
• Merge to development branch
• Update CHANGELOG.md
• Plan Phase 5 follow-up tasks (external adapters)

---

Quick Reference: Key Files

Purpose	File Path
Adapter Interface	packages/noodl-runtime/src/api/adapters/cloudstore-adapter.ts
LocalSQL Adapter	packages/noodl-runtime/src/api/adapters/local-sql/LocalSQLAdapter.ts
Backend Server	packages/noodl-editor/src/main/src/local-backend/LocalBackendServer.ts
Backend Manager	packages/noodl-editor/src/main/src/local-backend/BackendManager.ts
Backend Model	packages/noodl-editor/src/editor/src/models/BackendModel.ts
Launcher UI	packages/noodl-editor/src/editor/src/views/Launcher/BackendManager/
Database Nodes	packages/noodl-viewer-cloud/src/nodes/database/
Trigger Nodes	packages/noodl-viewer-cloud/src/nodes/triggers/
Workflow Compiler	packages/noodl-editor/src/editor/src/utils/workflow-compiler.ts
Backend Bundler	packages/noodl-editor/src/editor/src/utils/deployment/backend-bundler.ts

---

Estimated Time by Phase

Phase	Description	Estimated Hours
A	LocalSQL Adapter	16-20
B	Backend Server	12-16
C	Workflow Runtime	12-16
D	Launcher Integration	8-10
E	Migration & Export	8-10
F	Standalone Deployment	8-10
Total		64-82 hours

Recommended Session Structure: 4-6 hour Cline sessions, one sub-phase per session