web-app-launcher/plans/mvp-web-app-launcher/phase-4-app-healthcheck.md

Phase 4: App Registry & Healthcheck

Status: ✅ Complete Parent plan: PLAN.md Domain: fullstack

Objective

Build the app (service) registry with CRUD operations, the icon resolution system, healthcheck scheduler with node-cron, and status APIs. Create the app management UI.

Tasks

• Task 1: Create src/routes/api/apps/+server.ts — GET (list), POST (create)
• Task 2: Create src/routes/api/apps/[id]/+server.ts — GET, PATCH, DELETE
• Task 3: Create src/routes/api/apps/[id]/status/+server.ts — GET healthcheck status
• Task 4: Implement src/lib/server/services/healthcheckService.ts — perform HTTP health checks
• Task 5: Implement src/lib/server/jobs/healthcheckScheduler.ts — node-cron scheduled pings
• Task 6: Implement src/lib/server/utils/iconResolver.ts — resolve icon by type (Lucide, Simple Icons, Dashboard Icons CDN, upload path)
• Task 7: Create src/routes/apps/+page.server.ts — load app list
• Task 8: Create src/routes/apps/+page.svelte — app registry list page
• Task 9: Create src/lib/components/app/AppCard.svelte — app card with status indicator
• Task 10: Create src/lib/components/app/AppForm.svelte — create/edit app form (Superforms)
• Task 11: Create src/lib/components/app/AppIconPicker.svelte — icon selection UI
• Task 12: Create src/lib/components/app/AppHealthBadge.svelte — status badge (online/offline/degraded/unknown)
• Task 13: Create src/routes/api/health/+server.ts — app health endpoint for Docker healthcheck
• Task 14: Handle custom icon uploads — file upload endpoint + static serving from static/uploads/

Files to Modify/Create

• src/routes/api/apps/+server.ts
• src/routes/api/apps/[id]/+server.ts
• src/routes/api/apps/[id]/status/+server.ts
• src/routes/api/health/+server.ts
• src/lib/server/services/healthcheckService.ts
• src/lib/server/jobs/healthcheckScheduler.ts
• src/lib/server/utils/iconResolver.ts
• src/routes/apps/+page.server.ts
• src/routes/apps/+page.svelte
• src/lib/components/app/AppCard.svelte
• src/lib/components/app/AppForm.svelte
• src/lib/components/app/AppIconPicker.svelte
• src/lib/components/app/AppHealthBadge.svelte

Acceptance Criteria

• Apps can be created, read, updated, deleted via API
• Healthcheck scheduler runs on configured intervals per app
• Status is correctly derived: online/offline/degraded/unknown
• Icon resolver correctly maps all icon types to renderable output
• App list page displays apps with status badges
• Docker health endpoint returns 200 when server is running

Notes

• Healthcheck runs in-process via node-cron (no external job runner)
• Default healthcheck: HTTP HEAD to app URL, expect 200, 5s timeout, 60s interval
• Store last N status records in AppStatus for history (sparklines are post-MVP)
• Custom icon uploads go to static/uploads/ (Docker volume mount)
• ⚠️ Big Bang: pages will be functional but minimally styled until Phase 7

Review Checklist

• All tasks completed
• Code follows project conventions
• No unintended side effects
• Build passes
• Tests pass (new + existing)

Handoff to Next Phase

All 14 tasks are implemented. Key artifacts available for Phase 5:

• API routes: /api/apps (GET/POST), /api/apps/[id] (GET/PATCH/DELETE), /api/apps/[id]/status (GET), /api/health (GET), /api/uploads (POST)
• Services: healthcheckService.ts provides checkAppHealth() and checkAllApps(); healthcheckScheduler.ts provides startScheduler()/stopScheduler() using node-cron
• Icon resolution: iconResolver.ts maps all 4 icon types (lucide, simple, url, emoji) to renderable objects; AppCard.svelte renders them with CDN fallback for simple-icons
• UI components: AppCard, AppForm (Superforms), AppIconPicker, AppHealthBadge are ready for embedding in board widgets
• File uploads: /api/uploads validates SVG/PNG/JPG/WebP under 1MB, saves to static/uploads/
• Page: /apps lists all registered apps with category filtering, search, and inline create form

Phase 5 can reference apps via appId in widgets. The appService.findAll() and appService.findById() include latest status in responses. The healthcheck scheduler should be started from hooks.server.ts or a startup hook in Phase 8.