web-app-launcher/plans/mvp-web-app-launcher/phase-2-database-services.md

Phase 2: Database Schema & Services Layer

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

Objective

Define the full Prisma database schema, run migrations, and build the core server-side services layer with shared Zod validation schemas and TypeScript type definitions.

Tasks

• Task 1: Define Prisma schema with all models: User, Group, UserGroup, App, AppStatus, Board, Section, Widget, Permission, SystemSettings
• Task 2: Run prisma migrate dev to create initial migration
• Task 3: Create TypeScript type definitions in src/lib/types/ (auth, app, board, widget, user, group, permission)
• Task 4: Create shared Zod validation schemas in src/lib/utils/validators.ts
• Task 5: Create API response envelope utility in src/lib/server/utils/response.ts
• Task 6: Implement authService.ts — password hashing, JWT sign/verify, refresh token management
• Task 7: Implement userService.ts — CRUD, findByEmail, role management
• Task 8: Implement groupService.ts — CRUD, user-group membership
• Task 9: Implement appService.ts — CRUD, search, status updates
• Task 10: Implement boardService.ts — CRUD with sections and widgets, default board
• Task 11: Implement permissionService.ts — check/grant/revoke permissions, hierarchical resolution
• Task 12: Create src/lib/utils/constants.ts — shared constants (roles, status values, defaults)
• Task 13: Create prisma/seed.ts — seed admin user, default groups, default board, sample apps

Files to Modify/Create

• prisma/schema.prisma — full schema definition
• prisma/seed.ts — seed script
• src/lib/types/*.ts — type definitions
• src/lib/utils/validators.ts — Zod schemas
• src/lib/utils/constants.ts — constants
• src/lib/server/utils/response.ts — API envelope
• src/lib/server/services/authService.ts
• src/lib/server/services/userService.ts
• src/lib/server/services/groupService.ts
• src/lib/server/services/appService.ts
• src/lib/server/services/boardService.ts
• src/lib/server/services/permissionService.ts

Acceptance Criteria

• Prisma schema validates and migration runs
• All services export clean async functions with proper types
• Zod schemas match Prisma models
• Seed script creates demo data
• No circular dependencies between services

Notes

• SystemSettings is a singleton row — use upsert pattern
• Permission resolution: User-level > Group-level > Default
• Widget config is JSON — stored as String in SQLite, parsed at application layer
• OAuth fields in SystemSettings should be encrypted at rest (handle in Phase 3)
• Permission model uses polymorphic pattern (entityType/targetType) without FK relations to avoid SQLite constraints
• ⚠️ Big Bang: services won't be wired to routes yet

Review Checklist

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

Handoff to Next Phase

What's ready for Phase 3:

• Prisma schema is defined and migrated. SQLite DB created at data/launcher.db.
• Prisma client is generated and available via src/lib/server/prisma.ts singleton.
• authService.ts provides: hashPassword, verifyPassword, signAccessToken, verifyAccessToken, generateRefreshToken, saveRefreshToken, validateRefreshToken, revokeRefreshToken, rotateTokens.
• userService.ts provides: findAll, findById, findByEmail, create, update, remove, updateRole, getUserGroups, count.
• groupService.ts provides: findAll, findById, findByName, findDefaultGroups, create, update, remove, addUser, removeUser, getGroupMembers, addUserToDefaultGroups.
• App.Locals updated to use email + displayName (aligned with User model).
• Zod validators available for all form/API input validation.
• API response envelope (success, error, paginated) in src/lib/server/utils/response.ts.
• Seed data includes: admin user (admin@localhost / admin123), admin + user groups, 5 sample apps, default board with 2 sections and widgets.
• Constants exported from src/lib/utils/constants.ts for roles, statuses, widget types, permission levels.
• tsx added as devDependency for running seed script.
• package.json has prisma.seed config (deprecated warning — migrate to prisma.config.ts in future).