API Reference

Backend API Endpoint Specifications (Cloudflare Workers + Hono)

All routes require a valid Clerk Bearer JWT Token passed in the HTTP Authorization header (Authorization: Bearer <clerk_token>). Cross-Origin Resource Sharing (CORS) is enabled globally.

Common Base URL

• Custom BYOC (Bring Your Own Cloud): https://<your-worker-subdomain>.workers.dev/api

Endpoint Reference

Method	Path	Description	Request Body	Response
GET	/api/pages	Fetch all active pages for current user	None	Page[]
POST	/api/pages	Create new page	Partial<Page>	Page
PUT	/api/pages/:id	Update existing page content/title	Partial<Page>	Page
DELETE	/api/pages/:id	Permanently delete page	None	{ success: true }
GET	/api/projects	Fetch all user projects	None	Project[]
POST	/api/projects	Create new project	Partial<Project>	Project
PUT	/api/projects/:id	Update project metadata	Partial<Project>	Project
DELETE	/api/projects/:id	Delete project	None	{ success: true }
GET	/api/issues	Fetch all user Kanban issues	None	Issue[]
POST	/api/issues	Create new Kanban task	Partial<Issue>	Issue
PUT	/api/issues/:id	Update issue status/priority/title	Partial<Issue>	Issue
DELETE	/api/issues/:id	Delete issue	None	{ success: true }
GET	/api/notifications	Fetch user notifications	None	NotificationItem[]

Data Synchronization & Differential Engine (smartSync)

Instead of performing expensive full-state replacements on every keystroke, DevWannaSpace uses a client-side differential engine (smartSync).

How smartSync Works:

1. In-Memory Cache: The client maintains an active state cache (stateCache.pages, stateCache.projects, etc.).
2. Delta Calculation:
   • added: Items in new array missing from old array → POST request.
   • removed: Items in old array missing from new array → DELETE request.
   • updated: Items whose updatedAt timestamp has changed → PUT request.
3. Optimistic Parallel Execution: All necessary HTTP calls are dispatched in parallel via Promise.all.
4. Status Bar Emission: Broadcasts 'saving' | 'saved' | 'error' events to subscribers (updating the UI sync indicator in the top navbar).

Error Resilience & Edge Case Handling

1. Vite Unhandled Rejection Safeguard: Parallel Promise.all requests in AppShell.tsx have individual .catch(() => {}) handlers attached prior to Promise.all evaluation. This prevents secondary asynchronous network failures from triggering Vite's full-screen Red Error Overlay.
2. Invalid Key Graceful Fallback: If invalid Clerk keys or incorrect API URLs are detected at runtime, the application catches the initialization failure and renders a friendly "Connection Failed" UI with direct access to the Self-Host settings panel.