# WorkOnClock Project Overview

Last updated: 2026-05-13

## Product Summary

WorkOnClock is a multi-tenant employee management, time tracking, screenshot monitoring, and admin operations platform.

The product currently has three main surfaces:

- Public website and web admin console in `apps/web`
- NestJS runtime API for desktop tracking in `apps/api`
- Electron desktop tracker in `apps/desktop`

Current project status: MVP-plus. Core tenant, user, project, role, time tracking, screenshot, settings, audit, and adhoc workflows exist. Production hardening, payments, signed installers, stronger automated tests, and legal/privacy launch gates are still pending.

## Monorepo Structure

```text
WorkOnClock/
├── apps/
│   ├── api/                      # NestJS runtime API used by desktop app
│   │   ├── src/
│   │   │   ├── app.controller.ts
│   │   │   ├── app.service.ts
│   │   │   ├── app.module.ts
│   │   │   ├── auth.guard.ts
│   │   │   ├── auth.decorators.ts
│   │   │   ├── database.service.ts
│   │   │   ├── password.service.ts
│   │   │   ├── main.ts
│   │   │   └── smoke-test.ts
│   │   └── storage/uploads/screenshots/ # Local development screenshot files
│   ├── desktop/                  # Electron tracker app
│   │   ├── src/
│   │   │   ├── main.js           # Main Electron process, tracking, capture, sync
│   │   │   ├── preload.js        # IPC bridge
│   │   │   ├── renderer.html     # Main desktop UI
│   │   │   ├── status.html       # Floating status bar UI
│   │   │   └── assets/
│   │   ├── build/                # Icons and signing entitlements
│   │   └── scripts/
│   └── web/                      # Next.js public website and admin console
│       ├── app/
│       │   ├── (site)/           # Public marketing/legal website
│       │   ├── admin/            # Authenticated admin console
│       │   ├── api/              # Next.js route handlers
│       │   ├── components/       # Shared UI components
│       │   ├── lib/              # Auth, DB, RBAC, email, validation, utilities
│       │   ├── login/
│       │   ├── register/
│       │   └── reset-password/
│       ├── prisma/
│       │   ├── schema.prisma
│       │   ├── seed.ts
│       │   └── migrations/
│       ├── scripts/
│       └── types/
├── packages/
│   └── shared/                   # Cross-surface types and permission defaults
├── docs/
│   ├── api-strategy.md
│   ├── legal-privacy-requirements.md
│   └── week1-mvp-release-checklist.md
├── package.json
├── pnpm-workspace.yaml
└── vercel.json
```

## Tech Stack

### Web and Admin

- Next.js 14 App Router
- React 18
- TypeScript
- Tailwind CSS
- NextAuth credentials auth
- Prisma Client
- MySQL
- Zod validation

### Runtime API

- NestJS 10
- TypeScript
- MySQL through `mysql2`
- JWT access and refresh tokens
- Shared permission defaults from `packages/shared`

### Desktop

- Electron 31
- Plain HTML/CSS/JS renderer
- Electron IPC through preload script
- Electron `safeStorage` for encrypted local session/outbox envelopes
- Electron Builder and `electron-updater`
- Talks to NestJS API at `http://localhost:4000/api`

## Local Services

- Web admin/public site: `http://localhost:3020`
- NestJS API: `http://localhost:4000/api`
- Desktop app: `npm run dev -w @workonclock/desktop`

Common local commands:

```bash
npm install
npm run dev -w @workonclock/api
npm run dev -w @workonclock/web
npm run dev -w @workonclock/desktop
npm run build -w @workonclock/web
npm run build -w @workonclock/api
npm run build -w @workonclock/desktop
```

## Internal Vercel Deployment

Implemented deployment assets:

- `apps/web/vercel.json`
- `apps/api/vercel.json`
- `apps/api/api/[...path].ts`
- `apps/api/src/server.ts`
- `docs/internal-vercel-deployment.md`

Recommended internal testing topology:

- Vercel project for `apps/web`.
- Vercel project for `apps/api`.
- MySQL hosted on the dev server and exposed securely to Vercel.
- Desktop internal builds point to the deployed API URL.

Important limitation:

- Vercel serverless filesystem storage is ephemeral. Screenshot uploads can be accepted by the API, but durable screenshot image viewing still requires private object storage or a non-serverless API host with persistent disk.

## Database

The active schema uses MySQL and `woc_*` tables.

Confirmed core tables:

- `woc_organizations`
- `woc_users`
- `woc_roles`
- `woc_permissions`
- `woc_teams`
- `woc_projects`
- `woc_time_entries`
- `woc_screenshots`
- `woc_adhoc_records`
- `woc_invite_tokens`
- `woc_password_reset_tokens`
- `woc_organization_settings`
- `woc_invoices`
- `woc_transactions`
- `woc_audit_logs`
- `_UserRoles`
- `_RolePermissions`
- `_ProjectUsers`

Prisma models in `apps/web/prisma/schema.prisma`:

- `Organization`
- `User`
- `Role`
- `Permission`
- `Team`
- `Project`
- `TimeEntry`
- `Screenshot`
- `AdhocRecord`
- `InviteToken`
- `PasswordResetToken`
- `EmailVerificationToken`
- `OrganizationSettings`
- `Invoice`
- `Transaction`
- `AuditLog`

Implemented database behavior:

- Tenant-owned records use `organizationId`.
- `SYSTEM_ADMIN` users may have no organization.
- Core admin queries are tenant-scoped.
- Tenant isolation smoke test exists in `apps/web/scripts/tenant-isolation-check.cjs`.
- NestJS runtime API has migration/drop logic for old non-prefixed tables.
- Screenshot idempotency uses stable object keys.
- Audit logs include `organizationId`.
- Production migration, backup, restore, and schema-contract runbook exists in `docs/production-runbook.md`.
- Email verification token table and migration exist.

Pending database work:

- Move screenshot storage from local filesystem to private object storage.
- Implement generated API/shared types from Prisma or a schema contract after the documented direction is approved.

## Authentication and Authorization

### Implemented

- NextAuth credentials login for web admin.
- JWT session strategy.
- Session includes role, permissions, and organization context.
- Middleware protects admin and API routes.
- Shared permission keys live in `packages/shared`.
- Web RBAC menu and route permissions are centralized in `apps/web/app/lib/rbac/permissions.ts`.
- NestJS API has JWT auth guard and route permission decorators.
- Desktop authenticates with NestJS login and refresh endpoints.
- Password hashing is implemented on both web and API surfaces.
- New self-registered web users receive email verification tokens.
- Web login blocks unverified self-registered users.
- CSRF posture review is documented in `docs/csrf-review.md`.
- Web auth smoke test exists as `npm run test:auth -w @workonclock/web`.
- Middleware rejects unexpected cross-origin authenticated write requests for protected API routes.

### Pending

- Continue expanding CSRF/origin regression tests as new write routes are added.
- Expand auth test coverage beyond smoke coverage for refresh, role enforcement, and tenant boundaries.
- Move rate limiting from in-memory storage to Redis/shared infrastructure before horizontal scaling.

## Public Website

Implemented under `apps/web/app/(site)`.

Pages implemented:

- `/`
- `/features`
- `/use-cases`
- `/pricing`
- `/download`
- `/security`
- `/contact`
- `/about`
- `/faq`
- `/privacy`
- `/terms`
- `/copyright`

Implemented features:

- Public SaaS marketing pages.
- Shared site layout, header, footer, navigation, and CTAs.
- Login/register links.
- Pricing page with plan cards.
- Download page for desktop app positioning.
- Security, privacy, terms, copyright, FAQ, and contact pages.
- Light/dark theme support.
- Contact form posts to `/api/contact` and sends through the shared email provider/fallback.
- Contact form email sets reply-to to the submitter address for sales follow-up.

Pending:

- Add real download links for signed desktop builds.
- Integrate contact submissions with CRM if needed.
- Add production analytics if required.
- Refresh public site visual system to match the newer admin/desktop polish.

## Signup and Onboarding

Implemented files:

- `apps/web/app/register/page.tsx`
- `apps/web/app/register/register-form.tsx`
- `apps/web/app/api/register/route.ts`
- `apps/web/app/api/invites/route.ts`
- `apps/web/app/api/email-verification/confirm/route.ts`
- `apps/web/app/admin/onboarding/page.tsx`

Implemented features:

- Public organization signup at `/register`.
- Creates organization, default project, default team, organization settings, roles, and org admin user.
- Invite acceptance through `/register?orgId=...&token=...`.
- Invite signup creates employee user in the invited organization.
- Invite token is marked as used.
- Basic registration rate limiting.
- Password minimum length validation.
- Professionalized registration UI.
- Duplicate organization name UX returns a clear conflict error.
- Registration generates unique organization slugs with collision retries.
- Email verification is sent after self-registration.
- Email delivery supports Resend via `RESEND_API_KEY` and `EMAIL_FROM`.
- Invite acceptance still signs the invited user in immediately because invite token possession verifies the email path.
- Admin onboarding wizard guides first project, team, and user setup.

Pending:

- Add resend-verification email action.
- Add deeper onboarding forms inline if the guided-links approach is not enough.

## Admin Console

Implemented under `apps/web/app/admin`.

Current admin modules:

- Dashboard
- Screenshots
- Projects
- Users
- Roles & Permissions
- Teams
- Billing
- Settings
- Audit Logs
- Integrations
- Webhooks
- Adhoc Records

Recent UI status:

- Admin shell has a dark professional sidebar.
- Dashboard, screenshots, and settings pages have been visually refreshed.
- Shared card/button/input styles exist in `apps/web/app/globals.css`.

### Admin Dashboard

Implemented file:

- `apps/web/app/admin/page.tsx`

Implemented features:

- Organization/user/project/pending-adhoc summary cards.
- Screenshot and running-now summary cards.
- Daily work-hours chart.
- Daily screenshot chart.
- User-wise work hours.
- Project-wise work hours.
- Team-wise work hours.
- Last 7/15/30 day filters.
- Custom date range filter.
- Date range boundaries are evaluated in the organization's configured timezone.
- Drilldowns for day, user, project, and team chart rows.
- Widget for employees not running WorkOnClock since morning.
- Reusable `ChartCard`.

Pending:

- Add export/reporting options.
- Add more advanced analytics such as utilization targets or anomaly detection if required.

### Users

Implemented files:

- `apps/web/app/admin/users/page.tsx`
- `apps/web/app/admin/users/[id]/page.tsx`
- `apps/web/app/admin/users/user-form.tsx`
- `apps/web/app/admin/users/user-edit-form.tsx`
- `apps/web/app/admin/users/user-actions.tsx`
- `apps/web/app/admin/users/invite-form.tsx`
- `apps/web/app/admin/users/user-import-form.tsx`
- `apps/web/app/api/users/route.ts`
- `apps/web/app/api/users/[id]/route.ts`
- `apps/web/app/api/users/export/route.ts`
- `apps/web/app/api/users/import/route.ts`

Implemented features:

- Create users.
- Edit users.
- Delete users.
- Assign roles, team, and projects.
- Active/inactive status.
- Search and filters.
- User detail page with recent activity.
- Password reset token generation and reset flow.
- Invite email flow.
- CSV export.
- Bulk CSV import with optional team, role, project, and status mapping.
- Downloadable CSV import template.
- Client-side import preview with basic row validation.
- Import API returns row-level errors for unresolved teams, roles, and projects.
- Audit logging on sensitive mutations.

Pending:

- Configure production email env: `RESEND_API_KEY`, `EMAIL_FROM`, `NEXTAUTH_URL`.
- Add quoted CSV parsing and a richer import wizard if non-technical admins will upload spreadsheet exports directly.
- Add stronger user lifecycle controls if required.

### Projects

Implemented files:

- `apps/web/app/admin/projects/page.tsx`
- `apps/web/app/admin/projects/[id]/page.tsx`
- `apps/web/app/admin/projects/project-form.tsx`
- `apps/web/app/admin/projects/project-actions.tsx`
- `apps/web/app/api/projects/route.ts`
- `apps/web/app/api/projects/[id]/route.ts`

Implemented features:

- Create project.
- Edit project name.
- Delete project.
- Soft archive when project has time entries.
- Prevent deletion of default project.
- Assign users to projects.
- Active/archived/all filters.
- Project detail page with assignments, tracked time, recent entries, and audit events.

Pending:

- Add project budgets.
- Add billable/non-billable settings.
- Add project-level reporting exports.

### Teams

Implemented files:

- `apps/web/app/admin/teams/page.tsx`
- `apps/web/app/admin/teams/[id]/page.tsx`
- `apps/web/app/admin/teams/team-form.tsx`
- `apps/web/app/admin/teams/team-edit-form.tsx`
- `apps/web/app/admin/teams/team-actions.tsx`
- `apps/web/app/api/teams/route.ts`
- `apps/web/app/api/teams/[id]/route.ts`

Implemented features:

- Create teams.
- Edit teams.
- Assign users to teams.
- Team list page.
- Team detail page.
- Delete empty teams.
- Block delete when users are assigned.
- Default team creation for new organizations.

Pending:

- Add team-level activity summary.
- Add team-level policy overrides if needed.

### Roles and Permissions

Implemented files:

- `apps/web/app/admin/roles/page.tsx`
- `apps/web/app/admin/roles/role-create-form.tsx`
- `apps/web/app/admin/roles/role-permissions-form.tsx`
- `apps/web/app/api/roles/route.ts`
- `apps/web/app/api/roles/[id]/route.ts`
- `apps/web/app/lib/rbac/permissions.ts`

Implemented features:

- Role and permission models.
- User-role mapping.
- Role-permission mapping.
- Default permission sets.
- Permission-based admin navigation.
- Permission-based middleware.
- Create custom roles.
- Edit role permission assignments.
- Delete unused custom roles.
- Audit role permission changes.
- Prevent removing last active `manage_roles` holder in an organization.
- Improved role management UI with role user counts.
- NestJS runtime permission evaluation reads persisted custom role permissions.

Pending:

- Add custom role archive/history if deleted roles need retention beyond audit logs.

### Screenshots

Implemented files:

- `apps/web/app/admin/screenshots/page.tsx`
- `apps/web/app/admin/screenshots/[id]/page.tsx`
- `apps/api/src/app.controller.ts`
- `apps/api/src/app.service.ts`
- `apps/api/src/database.service.ts`
- `apps/desktop/src/main.js`
- `apps/desktop/src/renderer.html`

Implemented features:

- Desktop screenshot capture through Electron `desktopCapturer`.
- Screenshot uploads to NestJS API as base64.
- API writes screenshot images to local upload storage in development.
- Screenshot metadata stored in `woc_screenshots`.
- Stable object keys avoid duplicate screenshot records on retry.
- Admin screenshot gallery.
- Employee/date filters.
- Cursor pagination.
- Screenshot detail page.
- Open original/download actions.
- Admin screenshot preview/download now goes through authenticated `/api/screenshots/[id]/image`.
- Screenshot view/download events are audited.
- Tenant-scoped screenshot queries.
- Manual `Capture Now` button in desktop app.
- Automatic capture shortly after tracking starts.
- Capture permission diagnostics and macOS Screen Recording settings shortcut.
- Retention cleanup action in admin settings.
- Scheduled retention cron route.

Pending:

- Configure `CRON_SECRET` in production.
- Move screenshot files to private object storage.
- Add private signed URLs instead of public static links.
- Add privacy controls such as app/site exclusions or blur/masking if legally required.
- Continue validating long-running 5-minute capture stability.

### Time Tracking

Implemented in:

- Desktop app
- NestJS API
- Admin dashboard
- Time entry Prisma/NestJS database layers

Implemented features:

- Start/finish tracking from desktop.
- Auto-start tracking after login/session restore.
- Active tracking entry persists locally.
- Heartbeat while tracking.
- Auto-clock-out stale running entries based on organization policy.
- Daily work/break timer.
- Activity/idle tracking.
- Admin dashboard analytics by user/project/team.
- Time entries connected to projects, teams, users, screenshots, and organization.

Pending:

- True offline clock-in when API is unreachable.
- Better conflict resolution for offline/queued tracking events.
- More detailed employee time reports.
- Payroll/export impact for approved adhoc records.

### Adhoc Records

Implemented files:

- `apps/web/app/admin/adhoc-records/page.tsx`
- `apps/web/app/admin/adhoc-records/[id]/page.tsx`
- `apps/web/app/admin/adhoc-records/adhoc-form.tsx`
- `apps/web/app/admin/adhoc-records/approval-buttons.tsx`
- `apps/web/app/api/adhoc-records/route.ts`
- `apps/web/app/api/adhoc-records/[id]/approve/route.ts`
- `apps/web/app/api/adhoc-records/[id]/reject/route.ts`

Implemented features:

- Missed clock-in submission.
- Admin/manager can create records for users.
- Pending/approved/rejected workflow.
- Reviewer and review timestamp.
- Rejection reason.
- Approval/rejection email notifications when enabled.
- Record detail page.
- Audit history panel.

Pending:

- Payroll/export impact.
- Better employee self-service view.
- Attachments or proof fields if required.

### Settings

Implemented files:

- `apps/web/app/admin/settings/page.tsx`
- `apps/web/app/admin/settings/settings-form.tsx`
- `apps/web/app/admin/settings/retention-actions.tsx`
- `apps/web/app/api/settings/route.ts`

Implemented features:

- Organization name.
- Timezone.
- Manager user-create setting.
- Email notification setting.
- Working hours.
- Auto clock-out enabled.
- Auto clock-out after hours.
- Idle detection minutes.
- Mandatory clock-in.
- Screenshots enabled.
- Screenshot interval minutes.
- Pause screenshots when idle.
- Screenshot retention days.
- Manual screenshot retention cleanup.
- Settings update audit log.
- Settings API currently uses raw SQL for organization name update to bypass a stale Prisma validation issue.

Pending:

- Per-user timezone overrides if needed.
- Better settings grouping and inline validation messages.
- Resolve underlying Prisma client mismatch permanently if it resurfaces.

### Audit Logs

Implemented files:

- `apps/web/app/admin/audit-logs/page.tsx`
- `apps/web/app/admin/components/audit-panel.tsx`
- `apps/web/app/api/audit-logs/route.ts`
- `apps/web/app/api/audit-logs/export/route.ts`
- `apps/web/app/lib/audit/audit.ts`

Implemented features:

- Tenant-scoped audit log list.
- System admin organization filter.
- Actor/action/target/date filters.
- CSV export.
- Per-record audit panels on project, team, screenshot, and adhoc detail pages.
- Sensitive admin mutations write audit logs.

Pending:

- Expand panels to billing/webhook/integration records when those modules mature.
- Add immutable/external audit sink for production.
- Add unusual access alerting.

### Billing

Implemented files:

- `apps/web/app/admin/billing/page.tsx`
- `apps/web/app/api/billing/route.ts`
- Prisma `Invoice` and `Transaction` models

Implemented features:

- Current plan display.
- Subscription status.
- Plan expiry date.
- Invoice list.
- Transaction list.
- Mock seed invoice and transaction.

Pending:

- Real payment provider integration.
- Plan management.
- Invoice PDF generation.
- Payment failure handling.
- Webhook ingestion from payment provider.

### Integrations and Webhooks

Implemented files:

- `apps/web/app/admin/integrations/page.tsx`
- `apps/web/app/admin/webhooks/page.tsx`

Implemented features:

- Placeholder admin pages.

Pending:

- Define integration providers.
- Add webhook model.
- Add signing secrets.
- Add retry logic.
- Add event delivery logs.
- Add UI for webhook endpoint management.

## Next.js API Routes

Implemented route handlers:

- `POST /api/register`
- `GET /api/orgs`
- `GET/POST /api/users`
- `PATCH/DELETE /api/users/[id]`
- `GET /api/users/export`
- `POST /api/users/import`
- `GET/POST /api/roles`
- `PATCH /api/roles/[id]`
- `GET/POST /api/projects`
- `PATCH/DELETE /api/projects/[id]`
- `GET/POST /api/teams`
- `PATCH /api/teams/[id]`
- `POST /api/invites`
- `GET/POST /api/adhoc-records`
- `POST /api/adhoc-records/[id]/approve`
- `POST /api/adhoc-records/[id]/reject`
- `GET /api/dashboard`
- `GET /api/billing`
- `GET/PATCH /api/settings`
- `POST /api/screenshots/retention`
- `GET /api/audit-logs`
- `GET /api/audit-logs/export`
- `POST /api/password-reset`
- `POST /api/password-reset/confirm`
- `GET /api/cron/screenshots-retention`
- `NextAuth /api/auth/[...nextauth]`

Implemented features:

- Zod validation for major write endpoints.
- Tenant-scoped queries.
- Permission checks.
- Rate limits for sensitive auth/onboarding routes.
- Structured JSON server logs for server errors.
- Request IDs in error responses.
- Audit logging on sensitive mutations.

Pending:

- Add automated API tests.
- Normalize response envelopes.
- Add cursor pagination for high-volume lists.
- Add full request access logging.
- Add external log aggregation.

## NestJS Runtime API

Implemented routes:

- `GET /api/health`
- `POST /api/auth/login`
- `POST /api/auth/refresh`
- `GET /api/auth/me`
- `GET/POST /api/teams`
- `GET/POST /api/teams/:teamId/policy`
- `GET /api/tracking/policy`
- `GET/POST /api/users`
- `POST /api/tracking/start`
- `POST /api/tracking/:entryId/stop`
- `GET /api/tracking`
- `GET /api/tracking/me`
- `POST /api/heartbeat`
- `POST /api/screenshots`
- `GET /api/screenshots`
- `GET /api/screenshots/me`
- `GET /api/audit-logs`
- `POST /api/retention/screenshots/run`

Implemented features:

- JWT login and refresh.
- Desktop runtime auth.
- MySQL `woc_*` database access.
- Tracking start/stop.
- Heartbeat and auto-clock-out.
- Screenshot ingestion.
- Screenshot idempotency.
- Local file writing for uploaded screenshots in development.
- Runtime audit logging with organization context.
- Tracking policy from organization settings.
- Runtime permission checks now read persisted user-role-permission mappings and fall back to shared defaults only when no role permissions are found.
- Runtime list/read/update endpoints are scoped to the authenticated user's organization.
- API smoke tests cover cross-tenant runtime boundaries for teams, users, policies, tracking, and screenshots.
- Vercel serverless entrypoint exists at `apps/api/api/[...path].ts`.

Pending:

- Add migration behavior tests.
- Decide whether NestJS remains runtime-only or if desktop traffic should move to Next route handlers later.
- Add additional runtime endpoints only if desktop/external clients need them.

## Electron Desktop App

Implemented files:

- `apps/desktop/src/main.js`
- `apps/desktop/src/preload.js`
- `apps/desktop/src/renderer.html`
- `apps/desktop/src/status.html`
- `apps/desktop/src/assets/app-icon.svg`
- `apps/desktop/src/assets/tray-icon.svg`

Implemented features:

- Electron app named WorkOnClock Desktop.
- Login against NestJS API.
- Session persistence.
- Encrypted local session/outbox envelopes through Electron `safeStorage` where available.
- Start and Finish controls.
- Auto-start tracking after login/session restore.
- Daily work/break totals.
- Activity/idle detection.
- Dashboard, Screenshots, and Settings views.
- Professionalized desktop UI.
- Manual `Capture Now` action.
- Timed screenshot capture.
- Immediate capture shortly after tracking starts.
- Screenshot upload with retry outbox.
- Durable outbox for failed screenshot uploads and stop events.
- Background retry.
- Heartbeat timer.
- Local stop when API auto-clocks out stale entry.
- Tray menu with status, open app, start, finish, sync, update check, and quit.
- Closing main window hides it while background tracking can continue.
- Floating status window.
- Screen Recording diagnostics and privacy settings shortcut.
- Local storage security diagnostics.
- Auto-update wiring with `electron-updater`.
- Icons and release packaging config.

Pending:

- Signed/notarized installers for macOS and Windows.
- CI secrets/certificates for release builds.
- True offline clock-in support.
- Richer desktop diagnostics.
- First-run permission onboarding flow.
- More robust long-running capture/upload monitoring.

## Shared Package

Implemented files:

- `packages/shared/src/index.ts`

Implemented features:

- Shared role type.
- Permission keys.
- Default permission sets.
- Shared permission helper.
- Shared user/team/time/screenshot/audit/tracking policy types.
- Used by both web and NestJS API.

Pending:

- Expand shared types to cover all Prisma models.
- Consider generating shared types from Prisma or OpenAPI/Zod schemas.
- Add shared API contract tests.

## API Ownership Strategy

Documented in `docs/api-strategy.md`.

Current decision:

- Next.js route handlers own admin/internal SaaS workflows.
- NestJS owns desktop runtime tracking and screenshot ingestion.
- `packages/shared` owns cross-surface contracts.

Pending:

- Continue preventing drift between Next.js Prisma logic and NestJS SQL logic.
- Decide later whether to keep NestJS as runtime API or consolidate into Next.js APIs.

## Legal and Privacy

Documented in `docs/legal-privacy-requirements.md`.

Implemented baseline:

- Privacy/security/legal pages exist on public site.
- Screenshot policy settings exist.
- Retention settings and cleanup exist.
- Audit logs exist for sensitive admin actions.
- RBAC exists for admin access.
- Screenshot view/download audit events are written by the authenticated screenshot image route.

Pending launch gates:

- Final privacy notice.
- Market-by-market legal basis.
- Labor/work council review where required.
- DPIA/PIA.
- Counsel sign-off.
- DSAR/export/delete workflows.
- Security controls verification.
- Private storage and signed screenshot access.

## Verification Status

Recently verified:

- `npm run build -w @workonclock/web`: passing
- `npm run build -w @workonclock/api`: passing
- `npm run build -w @workonclock/desktop`: passing
- API health endpoint returns OK locally.
- Web admin runs locally on port `3020`.
- API runs locally on port `4000`.
- Desktop app launches locally.

Existing verification assets:

- GitHub Actions CI workflow: `.github/workflows/ci.yml`
- Tenant isolation smoke test: `npm run test:tenant -w @workonclock/web`
- Web auth smoke test: `npm run test:auth -w @workonclock/web`
- Web E2E smoke test: `npm run test:e2e -w @workonclock/web`
- Resend email smoke test: `EMAIL_SMOKE_TO=you@example.com npm run test:email -w @workonclock/web`
- NestJS runtime smoke test: `npm run test -w @workonclock/api`
- Prisma validation: `npm exec -w @workonclock/web -- prisma validate --schema prisma/schema.prisma`

Pending verification work:

- Expand E2E from smoke coverage to browser-driven UI automation if required.
- Add desktop smoke tests.
- Add production migration checks.

## Recent Work

Recent work has been split into commits for:

- Desktop screenshot behavior and desktop UI refresh.
- Web admin visual refresh for layout/dashboard/screenshots/settings.
- Settings API raw SQL workaround for organization name update.
- Production migration and backup runbook.
- Contact form backend.
- Registration, email verification, and onboarding.
- CSRF review, origin enforcement, and auth smoke test.
- Custom role deletion.
- Authenticated screenshot image access and audit logging.
- NestJS persisted custom role permission evaluation.
- GitHub Actions CI validation.
- User import template, preview, and row-level validation.
- Resend email configuration documentation and smoke test.
- Web E2E smoke coverage for registration, admin flows, role enforcement, tenant boundaries, dashboard API, and screenshot image access.
- NestJS runtime cross-tenant boundary tests.
- Dashboard daily charts, drilldowns, and organization-timezone-aware date ranges.
- Vercel-ready web/admin and NestJS API configuration for internal testing.

Generated screenshot files are runtime artifacts and should not be committed unless intentionally used as fixtures.

## Highest Priority Pending Work

1. Validate screenshot capture continuously over a real session.
2. Add actual production secrets for `RESEND_API_KEY`, `EMAIL_FROM`, `CONTACT_TO`, and `CRON_SECRET`.
3. Move screenshots to private object storage with signed access.
4. Complete legal/privacy launch gates.
5. Implement signed/notarized desktop installers.
6. Build real billing provider integration.
7. Add browser-driven UI E2E and desktop smoke tests if required for release gates.
8. Add production migration checks.
9. Decide long-term API consolidation strategy.

## Known Risks

- Two API surfaces exist: Next.js for admin workflows and NestJS for desktop runtime.
- NestJS uses direct SQL while web admin uses Prisma.
- Desktop screenshot capture depends on OS permissions.
- Local screenshot files are currently development storage.
- Vercel serverless API storage is ephemeral until object storage is implemented.
- Production email depends on environment configuration.
- Billing is placeholder/mock-backed.
- Integrations and webhooks are placeholders.
- Automated coverage is still limited.
- Legal/privacy readiness is not complete for external monitoring rollout.