KAIDLY

Elektripaigaldise käit. Lihtsalt. — a digital operations logbook for electrical installations: käidupäevik, käidukava, puudused and dokumendid in one place.

Next.js 16 (App Router) · TypeScript · Supabase (Postgres, Auth, Storage) · Tailwind CSS · Vercel.

Project documentation lives in docs/ and agent instructions in CLAUDE.md.

Requirements

• Node.js 24 (see .nvmrc; ≥ 22.18 required)
• A Docker-compatible container runtime for the local database (Docker Desktop, Colima, Podman, …)
• Everything else, including the Supabase CLI, is installed by npm install at pinned versions.

Setup

npm install
cp .env.example .env.local     # then fill in the DEVELOPMENT project's values
npm run dev                    # http://localhost:3000

.env.local needs exactly two required values from the hosted development Supabase project (Project Settings → API / API Keys):

Variable	Value
NEXT_PUBLIC_SUPABASE_URL	https://<project-ref>.supabase.co — no path
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	the publishable key (sb_publishable_…)

Production deployment, the full environment-variable inventory (Preview vs Production) and the launch runbook: docs/DEPLOYMENT.md and docs/RELEASE_CHECKLIST.md. Production uses its own Supabase project and additionally KAIDLY_SITE_URL=https://kaidly.ee.

Optional (server-side only, not a secret; set it in Vercel for Preview/Production too):

Variable	Value
KAIDLY_CONTACT_EMAIL	address for the "Soovin jätkata" link when a company's trial or full access has ended (subject "KAIDLY täiskasutuse jätkamine (…)"). Without it the notice only says to contact KAIDLY, with no link. Never put a personal address in source code.

Never add the service_role / secret key. If configuration is missing or invalid, the app refuses to run and says what's wrong (it does not fall back to skipping authentication).

Local database and tests

npm run db:start      # start local Supabase (first run downloads images)
npm run db:reset      # rebuild the local database from supabase/migrations + seed.sql
npm run test:db       # pgTAP database/RLS tests in supabase/tests
npm run db:types      # regenerate lib/supabase/database.types.ts
npm run db:stop

Development seed (local only)

npm run db:reset also loads supabase/seed.sql: a fictional demo organisation ("Näidis Elektritööd OÜ", /o/naidis-elektritood-demo) with two sites, five installations, log entries, scheduled activities and deficiencies. Demo accounts — password kaidly-demo-parool:

Email	Role
[email protected]	owner
[email protected]	admin
[email protected]	operator
[email protected]	viewer

The seed only ever runs against the local database (supabase db push never runs seeds). To browse it, run the app against the local stack: npm run dev:local.

Sample documents and photos (generated locally, no downloads) go through the normal upload flow, signed in as the demo users — run after each reset:

npm run db:seed-files

QA fixtures (local only)

Realistic fictional QA companies for manual testing and dogfooding (password for every QA account: kaidly-qa-parool; accounts listed at the top of supabase/qa/qa_fixtures.sql):

npm run db:reset && npm run qa:fixtures            # QA Elektritööd OÜ (trial), QA Tööstuspark OÜ (active),
                                                    # QA Haldus OÜ (expired), QA Suletud OÜ (deactivated)
npm run qa:fixtures -- --perf                       # + QA Jõudlus: 30 sites, 150 installations, 2000 log
                                                    #   entries, 500 activities, 300 deficiencies, 500 documents
npm run db:reset                                    # remove / reset (rebuilds the local database)

scripts/qa-fixtures.mjs writes only inside the local database container and aborts if the production project ref appears anywhere in the environment or the CLI link, or if the target isn't localhost (scripts/qa-guard.mjs, unit-tested). Document rows are metadata only (no files). There is deliberately no hosted variant.

Storage consistency (stale pending uploads, orphaned objects; read-only):

docker exec -i supabase_db_kaidly psql -U postgres < supabase/maintenance/storage_report.sql

End-to-end tests (local only)

npm run db:start          # local Supabase must be running
npx playwright install chromium   # once
npm run test:e2e          # starts its own dev server on port 3100 against the local stack

The Playwright suite (e2e/) refuses to run against anything but localhost. Test users are created through the local auth admin API and fixture rows with SQL as the local postgres user; the service-role key is read from supabase status at runtime and never stored. Every test runs on desktop (1440 px); tests tagged @responsive also run on a phone (375 px) and a tablet (768 px).

Full check before every commit:

npm run check         # lint, typecheck, unit tests, database tests, production build
npm run test:e2e      # browser tests (local Supabase running)

To run the app against the local stack instead of the development project:

npm run dev:local        # http://localhost:3000, reads the local values from `supabase status`

Local auth emails are caught by Mailpit (URL in npx supabase status).

Languages

The UI is Estonian by default, with English and Russian (lib/i18n/{et,en,ru}.ts). The language is chosen in the public header or the account menu and kept in a cookie and, for signed-in users, in their profile. Russian terminology still needs review by a native electrical professional before public launch.

Continuous integration

.github/workflows/ci.yml runs on pull requests and on pushes to every branch except main: lint, typecheck, unit tests and build; database tests on a fresh local Supabase stack inside the runner (plus a check that lib/supabase/database.types.ts matches the migrations); and the Playwright suite. It needs no secrets and never touches a hosted project. Traces of failed browser tests are kept as a build artifact for 7 days.

Database changes

All schema, policy and storage changes are migrations:

npx supabase migration new <name>   # write SQL, then:
npm run db:reset && npm run test:db && npm run db:types

No manual changes in the Supabase dashboard. See docs/DATABASE.md.

Hosted development project (one-time, manual)

Migrations are applied to the hosted project with the CLI. This needs your Supabase account and the database password, so it is done by hand:

npx supabase login
npx supabase link --project-ref <project-ref>   # asks for the database password
npx supabase db push                            # applies supabase/migrations

Before the first push, check that the hosted Postgres major version matches supabase/config.toml (major_version = 17): in the dashboard SQL editor run show server_version;.

Auth settings for the hosted project (Authentication → URL Configuration / Providers):

• Site URL: http://localhost:3000 for development (production URL later).
• Redirect URLs: http://localhost:3000/** (add preview/production URLs when they exist).
• Email confirmations: on. Minimum password length: 10.
• Optional, recommended: in the "Confirm signup" and "Reset password" email templates use {{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email&next={{ .RedirectTo }} (and type=recovery for reset), so links work even when opened in a different browser. The default templates also work, but only in the browser where the user started.