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

Phase 2: Database Schema & Services Layer

Status: ⬜ Not Started 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 — use Prisma Json type
• OAuth fields in SystemSettings should be encrypted at rest (handle in Phase 3)
• ⚠️ 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