# WorkOnClock API Strategy

## Decision

WorkOnClock will keep two API surfaces for now, with explicit ownership:

- Next.js App Router route handlers own SaaS/admin workflows.
- NestJS owns desktop runtime ingestion: tracking, heartbeat, screenshots, and desktop auth.

This is safer than a large rewrite today because the desktop app already depends on the NestJS runtime API. The scalability path is to remove drift through shared contracts, shared permission defaults, and consistent database rules before deciding whether to migrate desktop runtime traffic into Next.js.

## Why this scales

For 10,000+ users, screenshot and heartbeat traffic is the most write-heavy part of the product. Keeping runtime ingestion isolated lets it scale independently from admin/dashboard traffic. The important rule is that both surfaces must use the same product contracts and tenant model.

## Ownership Rules

Next.js owns:

- Organization registration
- Admin dashboard
- Users, roles, permissions
- Projects and teams
- Settings
- Billing UI and billing APIs, when enabled
- Invites and password reset
- Adhoc records
- Audit log views

NestJS owns:

- Desktop login and token refresh
- Tracking start/stop
- Heartbeat and auto clock-out checks
- Screenshot upload and screenshot retention execution
- Desktop-facing activity and screenshot reads

Shared package owns:

- Permission keys
- Default role-permission mappings
- Desktop/API DTO interfaces
- Tracking policy shape

## Drift Prevention

- Permission keys and role defaults must come from `packages/shared`.
- Admin settings that affect desktop behavior must be stored in `woc_organization_settings`.
- NestJS must read runtime policy from `woc_organization_settings`, not local constants.
- New cross-surface API shapes should be added to `packages/shared` first.
- Raw SQL in NestJS must always include organization scope when reading tenant data.
- Next.js Prisma queries must use tenant scope helpers or explicit `organizationId` filters.

## Future Consolidation Trigger

Consider moving desktop runtime APIs into Next.js only when:

- Admin and runtime tests are comprehensive.
- Screenshot upload/storage is backed by object storage.
- Rate limiting is backed by a shared store.
- Background jobs exist for retention and retry work.
- Desktop can switch endpoint versions without forcing every installed client to upgrade immediately.

Until then, consolidation should mean shared contracts and shared rules, not a risky one-step rewrite.