# Phase 2: Database Schema & Services Layer

**Status:** ✅ Complete
**Parent plan:** [PLAN.md](./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

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

- [x] All tasks completed
- [x] Code follows project conventions
- [x] 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).