Yrka

Yrka is a pnpm/Turbo monorepo whose production priority is a mobile-friendly workforce platform for timekeeping, scheduling, employee records, operational communications, resources, payroll-prep handoff, and permissioned management workflows. The authenticated web application uses Supabase Auth/Postgres with Row Level Security and server-owned route-action seams for sensitive writes.

The full repository contains adjacent experiments and operator tools as well. They are not all part of the workforce launch promise. The current portfolio status, boundaries, and sequencing live in docs/product/platform/portfolio-status.md.

Workspace Topology

• apps/web — authenticated workforce product on app.yrka.io.
• apps/marketing — public marketing, legal, and contact site on yrka.io and www.yrka.io.
• apps/docs — Mintlify customer manual on docs.yrka.io.
• apps/boardrune — isolated static browser experiment.
• apps/growth/growth-intelligence and apps/internal/developer-dashboard — internal tools, not customer-facing workforce product paths.
• apps/desktop — hosted-app Electron companion; distribution remains gated on signed artifacts and update-host readiness.
• packages — shared domain, database, authentication, UI, and product-supporting packages.

See apps/README.md for the durable app inventory and docs/operations/local-and-release/deployment-topology.md for deployment ownership, domains, and environment boundaries.

Tech Stack

• Next.js 16 App Router
• React 19
• TypeScript
• Tailwind CSS 4
• Supabase Auth and Postgres
• SWR for client-side data fetching
• Vercel Analytics

Quick Start

Install dependencies:

pnpm install

Pull environment variables from Vercel:

vercel link --yes
vercel env pull .env.local --yes --environment=development

Run the app:

pnpm dev

Open http://localhost:3000.

Environment Variables

The app needs Supabase browser credentials:

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
NEXT_PUBLIC_DEV_SUPABASE_REDIRECT_URL=

Use .env.local for real values. Do not commit .env.local.

See docs/operations/local-and-release/environment.md for details.

Useful Commands

pnpm dev      # Start local dev server
pnpm lint     # Run ESLint
pnpm typecheck  # Run TypeScript without emitting files
pnpm test     # Run Vitest unit and integration tests
pnpm test:smoke  # Run all Playwright browser smoke tests
pnpm test:smoke:admin  # Run the seeded-admin dashboard smoke
pnpm test:smoke:employee  # Run the seeded employee self-service smoke
pnpm run audit  # Run dependency audit at moderate severity and above
pnpm db:migrate:dry  # Dry-run the active Supabase migration package
pnpm db:migrate  # Apply supabase/migrations to the configured target
pnpm db:verify  # Verify the fresh launch-baseline target shape
pnpm db:verify:baseline  # Alias for launch-baseline verification
pnpm db:verify:historical  # Verify a historical target that still includes compatibility tables
pnpm db:snapshot  # Write a database catalog verification snapshot under docs/operations/evidence
pnpm db:snapshot:baseline  # Write a launch-baseline catalog verification snapshot under docs/operations/evidence
pnpm supabase:types  # Refresh packages/db/src/database.types.ts from the configured live database
pnpm build    # Build production bundle
pnpm start    # Start production server after build
pnpm brand:icons  # Regenerate favicons, PWA icons, and desktop icons from public/icon.svg
pnpm desktop:pack:win  # Build the unsigned Windows desktop installer under artifacts/desktop
pnpm check    # Run boundaries, typecheck, tests, lint, and build
pnpm check:smoke  # Run the browser/API smoke suite
pnpm check:launch  # Run the local/PR gate, then the smoke release gate
pnpm clean:local  # Remove local generated artifacts, dev logs, smoke output, and legacy output roots
pnpm seed:demo  # Create seeded admin, employees, schedules, payroll, resources, tasks, training, imports, and timecards
pnpm verify:sentry  # Send a Sentry verification exception using local env
pnpm customer:export -- --deletion-dry-run  # Verify customer export manifest shape
rg "pattern" .  # Fast recursive repo search
grep "literal" path\\to\\file  # Narrow single-file or piped text filtering

Desktop packaging details live in docs/operations/local-and-release/desktop/desktop-companion-release-runbook.md. For Windows, rebuild the bundled desktop installer with pnpm desktop:pack:win; the installer is written to artifacts/desktop/Yrka Setup 0.1.0.exe, and the unpacked runnable app lives at artifacts/desktop/win-unpacked/Yrka.exe after a successful build. Local unsigned builds use an inert placeholder update URL when YRKA_DESKTOP_UPDATE_URL is not set; signed release promotion still requires pnpm desktop:release:check. Rebuild after desktop shell changes, Electron package metadata changes, icon changes, or when you need a fresh installer to distribute. Ordinary hosted web app changes do not require rebuilding the installer because the Electron shell loads the configured Yrka URL at runtime.

Preview the demo seed without writing to Supabase:

pnpm seed:demo -- --dry-run

The demo seed creates one stable admin user, demo-admin@example.com, plus 20 confirmed employee users named demo-employee+01@example.com through demo-employee+20@example.com. Reruns refresh only those seeded demo accounts and their demo data, including schedule override, leave adjustment, resource, task, training, notification, import, integration, and customer lifecycle examples. Use pnpm seed:demo -- --dry-run to preview feature-area row counts without writing to Supabase.

Demo Path

Run the seed, then log in with one of the shipped demo accounts:

pnpm seed:demo

• Admin: demo-admin@example.com
• Employee: demo-employee+01@example.com

For a quick browser verification pass, run:

pnpm exec playwright install chromium
pnpm test:smoke

Testing standards live in docs/engineering/quality/testing-standards.md. Prefer focused unit, integration, or targeted smoke coverage for the behavior at risk; do not use broad smoke tests for volatile copy, routine UI polish, or details that are faster and safer to verify during product review.

CI

Repository CI runs on Windows and enforces install, boundaries, typecheck, Vitest, lint, production build, dependency audit, and a migration dry run. The staging smoke workflow is manually dispatched with SMOKE_BASE_URL and uploads Playwright traces, screenshots, videos, and reports from artifacts/playwright. Database verification is a separate environment-protected workflow that applies supabase/migrations and runs pnpm db:verify against the configured target.

Main Routes

The authenticated product uses canonical employee and admin destinations. The employee shell owns /employee/today, /employee/schedule, and /employee/profile; the admin shell owns /admin and its named workspace destinations such as /admin/personnel, /admin/tasks, and /admin/settings/billing. /clock is the authenticated organization-scoped kiosk timeclock. Public system endpoints include /api/health and /api/webhooks/stripe; /auth/login and /auth/sign-up own authentication and self-serve organization provisioning.

Legacy /calendar and /profile URLs are canonicalized through the route ownership contract rather than treated as primary product routes. See docs/engineering/architecture/route-ownership.md.

Admin Access

Admin access is controlled by organization-scoped RBAC in organization_member_roles and admin_role_permissions. Self-serve signups create a new organization and assign the signing user the owner role. Profile-level admin flags are not part of the launch database shape.

More context is in docs/product/workflows/README.md.

Database

Apply migrations with pnpm db:migrate. The current executable package is supabase/migrations and applies through Supabase's CLI ledger. The canonical migration order and apply rules live in docs/engineering/data-platform/migrations-and-baseline.md, not in this README.

The schema covers profiles, self-serve organization provisioning, jobs, timecard entries, app settings, company payroll settings, employee records, documents, credentials, notes/messages, payroll snapshots, company jobs, holidays, leave-ledger/access tables, schedule assignments/overrides, Resources/Handbook/Directory tables, integration ledgers, notifications, training, Work/Tasks, organization onboarding, Stripe billing lifecycle state, and admin seams for the shipped workflows. It enables Row Level Security, policies, triggers, storage policies, employee-message RPCs, resource acknowledgements, and source metadata for later knowledge indexing.

This repo is greenfield. The current schema baseline is required; we do not preserve legacy schema compatibility just to protect demo history. The seed expects the base schema to already be applied, then reapplies the foundation scripts as part of pnpm seed:demo.

pnpm db:verify and pnpm db:verify:baseline can use direct Postgres envs or, when those are absent, the repo's linked Supabase project through supabase db query --linked. Use pnpm db:verify or pnpm db:verify:baseline for linked or fresh launch-baseline projects that intentionally omit historical compatibility tables. Use pnpm db:verify:historical only for an older target that still carries the historical compatibility tables.

Supabase type generation is repo-local and Windows-friendly: pnpm supabase:types reads .env.local, connects through POSTGRES_URL_NON_POOLING or POSTGRES_URL, and refreshes packages/db/src/database.types.ts. The generated file records live schema table, column, relationship, enum, and function metadata. Supabase client factories use the generated Database type, and shared domain types derive from the generated row/insert/update contracts.

See docs/engineering/data-platform/README.md.

Project Docs

Keep this top-level README stable: link to durable directories or canonical docs, not dated research, dated roadmaps, release evidence, or individual migration files. Detailed file-level migration order belongs in docs/engineering/data-platform/migrations-and-baseline.md, and artifact-lifecycle material belongs behind docs/README.md.

• docs/README.md - docs index
• docs/operations/local-and-release/setup.md - local setup and verification
• docs/operations/local-and-release/environment.md - environment variables and Vercel pulls
• docs/engineering/architecture/architecture.md - app structure and important files
• docs/engineering/data-platform/README.md - Supabase schema, RLS, auth, migrations, and verification
• docs/product/workflows/README.md - employee/admin product workflows
• docs/product/platform/qa-checklist.md - manual regression checklist
• docs/research/ - active research, audits, and feasibility notes
• docs/roadmaps/ - active implementation plans