# Phase 2: Database Schema & Services Layer

**Status:** ⬜ Not Started
**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

- [ ] 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
<!-- Filled in by the implementation agent after completing this phase. -->