web-app-launcher/plans/phase-4-7-full-expansion/phase-1-schema-types.md

Phase 1: Database Schema & Type Foundation

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

Objective

Define all new database models, extend existing models, add new widget type constants, create TypeScript type definitions, and write Zod validation schemas for every new entity across Phases 4–7.

Tasks

1.1 Extend Prisma schema with new models

• Add Tag model (id, name, color, createdAt)
• Add AppTag junction model (appId, tagId)
• Add AppLink model (id, appId, label, url, icon, order)
• Add UserFavorite model (id, userId, appId, order)
• Add AppClick model (id, userId, appId, clickedAt)
• Add NotificationChannel model (id, userId, type, config JSON, enabled, createdAt)
• Add Notification model (id, userId, appId, event, message, sentAt, readAt)
• Add ApiToken model (id, userId, name, tokenHash, scope, lastUsedAt, expiresAt, createdAt)
• Add AuditLog model (id, userId, action, entityType, entityId, details JSON, createdAt)
• Add BoardTemplate model (id, name, description, icon, config JSON, isBuiltin, createdById, createdAt)

1.2 Extend existing Prisma models

• Board: add themeHue (Int?), themeSaturation (Int?), backgroundType (String?), cardSize (String?), wallpaperUrl (String?), wallpaperBlur (Int?), wallpaperOverlay (Float?), customCss (String?)
• Section: add cardSize (String?)
• User: add onboardingComplete (Boolean, default false), trackRecentApps (Boolean, default true)
• SystemSettings: add customCss (String?), onboardingComplete (Boolean, default false)

1.3 Add relations to existing models

• App → tags (via AppTag), links (AppLink[]), clicks (AppClick[]), notifications (Notification[])
• User → favorites (UserFavorite[]), clicks (AppClick[]), notificationChannels (NotificationChannel[]), notifications (Notification[]), apiTokens (ApiToken[]), auditLogs (AuditLog[]), boardTemplates (BoardTemplate[])
• Board → (themeHue, themeSaturation etc. are scalar fields, no new relations needed)

1.4 Generate and apply Prisma migration

• Run npx prisma migrate dev --name phase4-7-schema to create migration
• Run npx prisma generate to update Prisma client

1.5 Extend widget type constants

• Add to WidgetType in src/lib/utils/constants.ts: CLOCK, SYSTEM_STATS, RSS, CALENDAR, MARKDOWN, METRIC, LINK_GROUP, CAMERA
• Add CardSize constant: COMPACT, MEDIUM, LARGE
• Add NotificationType constant: DISCORD, SLACK, TELEGRAM, HTTP
• Add NotificationEvent constant: APP_ONLINE, APP_OFFLINE, APP_DEGRADED
• Add ApiTokenScope constant: READ, WRITE, ADMIN
• Add AuditAction constant: USER_CREATED, USER_DELETED, USER_UPDATED, BOARD_CREATED, BOARD_DELETED, APP_CREATED, APP_DELETED, SETTINGS_UPDATED, IMPORT, EXPORT
• Add BackgroundType extension if needed (wallpaper type)

1.6 Create TypeScript type definitions

• Create src/lib/types/tag.ts — Tag, AppTag, CreateTagInput, UpdateTagInput
• Create src/lib/types/notification.ts — NotificationChannel, Notification, CreateChannelInput, NotificationPreferences
• Create src/lib/types/apiToken.ts — ApiToken, CreateTokenInput, TokenScope
• Create src/lib/types/auditLog.ts — AuditLog, AuditAction, CreateAuditLogInput
• Create src/lib/types/template.ts — BoardTemplate, CreateTemplateInput
• Extend src/lib/types/widget.ts — add config interfaces for all 8 new widget types:
  • ClockWeatherWidgetConfig: { timezone, showWeather, latitude?, longitude?, clockStyle }
  • SystemStatsWidgetConfig: { sourceUrl, sourceType, metrics[], refreshInterval }
  • RssWidgetConfig: { feedUrl, maxItems, showSummary }
  • CalendarWidgetConfig: { icalUrls: Array<{url, color, label}>, daysAhead }
  • MarkdownWidgetConfig: { content, syntaxTheme }
  • MetricWidgetConfig: { label, source, value?, url?, jsonPath?, query?, unit?, refreshInterval }
  • LinkGroupWidgetConfig: { links: Array<{label, url, icon?}>, collapsible }
  • CameraWidgetConfig: { streamUrl, type, refreshInterval, aspectRatio }
• Extend src/lib/types/app.ts — add AppLink type, extend App type with links[] and tags[]
• Extend src/lib/types/user.ts — add UserFavorite, AppClick, extend User with new fields
• Extend src/lib/types/board.ts — add theme/visual fields to Board type

1.7 Create Zod validation schemas

• Add widget config schemas in src/lib/utils/validators.ts for all 8 new widget types
• Add createTagSchema, updateTagSchema
• Add createAppLinkSchema, updateAppLinkSchema
• Add createNotificationChannelSchema, updateNotificationChannelSchema
• Add createApiTokenSchema
• Add createBoardTemplateSchema
• Add auditLogQuerySchema (filters: action, entityType, dateRange)
• Update createWidgetSchema to accept new widget type values
• Update updateBoardSchema to accept new theme/visual fields
• Update updateSectionSchema to accept cardSize
• Update updateUserSchema to accept onboardingComplete, trackRecentApps

Files to Modify/Create

• prisma/schema.prisma — extend with all new models and fields
• src/lib/utils/constants.ts — new constant objects
• src/lib/types/tag.ts — new file
• src/lib/types/notification.ts — new file
• src/lib/types/apiToken.ts — new file
• src/lib/types/auditLog.ts — new file
• src/lib/types/template.ts — new file
• src/lib/types/widget.ts — extend with 8 new config interfaces
• src/lib/types/app.ts — extend with AppLink, tags
• src/lib/types/user.ts — extend with favorites, clicks, new fields
• src/lib/types/board.ts — extend with visual/theme fields
• src/lib/utils/validators.ts — all new Zod schemas

Acceptance Criteria

• All new Prisma models have correct fields, types, relations, and indexes
• Migration applies cleanly to a fresh SQLite database
• Prisma client generates without errors
• All TypeScript types use readonly for immutability
• All Zod schemas validate correct inputs and reject invalid ones
• New widget types are added to WidgetType constant
• Existing code is not broken by schema additions (additive changes only)

Notes

• All new fields on existing models must be optional or have defaults to avoid breaking existing data
• Use cuid() for all new model IDs consistent with existing schema
• Store JSON configs as String in Prisma (SQLite limitation), parse with Zod on read
• Keep immutable patterns — all type interfaces use readonly

Review Checklist

• All tasks completed
• Code follows project conventions
• No unintended side effects
• Build passes (Big Bang: code quality check only)
• Tests pass (Big Bang: skipped for intermediate phase)

Handoff to Next Phase

What was done

• Extended Prisma schema with 10 new models: Tag, AppTag, AppLink, UserFavorite, AppClick, NotificationChannel, Notification, ApiToken, AuditLog, BoardTemplate
• Extended existing models (User, Board, Section, SystemSettings) with new fields
• Added all relations between new and existing models
• Migration 20260325092024_phase4_7_schema created and applied successfully
• Prisma client regenerated
• Added 7 new constant objects: CardSize, NotificationType, NotificationEvent, ApiTokenScope, AuditAction, BackgroundType, plus 8 new widget types
• Created 5 new type files: tag.ts, notification.ts, apiToken.ts, auditLog.ts, template.ts
• Extended 4 existing type files: widget.ts (8 new config interfaces), app.ts (AppLink + AppWithRelations), user.ts (UserFavorite, AppClick, UserWithPreferences), board.ts (theme/visual fields)
• Added 19 new Zod schemas and updated 4 existing schemas in validators.ts

What the next phase needs to know

• All new Prisma models are available via the generated client
• Widget type enum in constants.ts now has 13 values (5 original + 8 new)
• All widget config Zod schemas follow the naming pattern {type}WidgetConfigSchema
• New entity schemas follow the naming pattern create{Entity}Schema / update{Entity}Schema
• auditLogQuerySchema supports pagination (page, limit) and date filtering (dateFrom, dateTo)
• App model still has legacy tags string field; the new AppTag junction table provides structured tagging
• All changes are additive — no breaking changes to existing API contracts

Potential concerns

• The legacy App.tags (comma-separated string) field still exists alongside the new AppTag junction. Later phases should decide whether to migrate data and deprecate the string field.
• updateSystemSettingsSchema was extended with customCss and onboardingComplete — existing settings API route handlers will need to pass these through.