community-rule/CONTRIBUTING.md

Contributing

Local backend

1. Copy .env.example to .env and set SESSION_SECRET (at least 16 characters).
2. docker compose up -d postgres mailhog — omit mailhog if you only need Postgres. Without CLOUDRON_MAIL_SMTP_*, the magic-link verify URL is printed in the dev server log.
3. npm ci
4. npx prisma migrate dev
5. (Optional) npx prisma db seed — seeds curated rule templates. Idempotent; rows upsert by slug.
6. npm run dev

Use npx prisma studio to inspect the database.

Deploying to staging or production (MEDLab Cloudron) — see docs/guides/ops-backend-deploy.md for the admin handoff and the linked Linear tickets for the actual deployment-pipeline work.

Prisma migrations

• Never edit a migration that has already been applied to staging, production, or any shared database. Add a new migration that corrects the schema instead. Full policy: docs/guides/backend-roadmap.md §8.
• Any change under prisma/: run npm run migrate:smoke (see docs/testing-guide.md, Prisma under Running tests).

API routes

Method	Path	Purpose
GET	/api/health	Liveness / DB check.
GET	/api/auth/session	Current user or null.
POST	/api/auth/magic-link/request	Send sign-in link email.
GET	/api/auth/magic-link/verify	Validate token, set cookie, redirect.
POST	/api/auth/logout	Clear session.
GET / PUT	/api/drafts/me	Load or save the create-flow draft.
POST	/api/uploads	Authenticated multipart upload (create-flow images / PDFs); requires UPLOAD_ROOT.
GET	/api/uploads/[id]	Stream a previously uploaded file by opaque id (public read).
GET / POST	/api/rules	List or publish rules.
GET	/api/templates	List curated templates. Optional repeatable facet.<group>=<value> query params re-rank results (and may include scores in the JSON). See docs/guides/template-recommendation-matrix.md §9.1.
GET	/api/templates/[slug]	Single curated template plus normalized { section, slug } composition from body. Public read; 404 when unknown. §9.4 (CR-115).
GET	/api/create-flow/methods	Public catalog for built-in governance methods and core values. Required section (communication | membership | decisionApproaches | conflictManagement | coreValues; alias values → coreValues). Returns the full deck with label, description, and sections (methods) or id, label, meaning, signals (core values). Optional facet.* adds matches and re-ranks method rows (ignored for coreValues). Core value id is a 1-based position string ("1", "2", …). English v1 only. §9.2 / §9.5 (CR-115).
POST / GET	/api/web-vitals	Ingest or read web vitals. Production default: external — structured logs only (no writes under .next; safe for read-only FS). Development default: local — aggregates under .next/web-vitals. Override with WEB_VITALS_STORAGE. See docs/guides/backend-roadmap.md §7.
GET	/api/rules/me	Authenticated list of own published rules.
GET / PATCH / DELETE	/api/rules/[id]	Public read; owner update/delete.
POST	/api/rules/[id]/duplicate	Owner clone of a published rule.
GET / POST	/api/rules/[id]/stakeholders	List or invite rule stakeholders.
DELETE	/api/rules/[id]/stakeholders/[stakeholderId]	Remove a stakeholder.
POST	/api/rules/[id]/stakeholders/[stakeholderId]/resend	Resend stakeholder invite email.
GET	/api/invites/rule-stakeholder/verify	Verify stakeholder invite token; redirect.
DELETE	/api/user/me	Delete authenticated user account.
POST	/api/user/email-change/request	Request email change (magic link to new address).
GET	/api/user/email-change/verify	Verify email-change token; update User.email.
POST	/api/organizer-inquiry	Submit ask-organizer inquiry form.
POST	/api/use-cases/[slug]/duplicate	Duplicate a use-case demo rule.

Magic-link sign-in

• Visit /login or use Log in in the site header.
• Without CLOUDRON_MAIL_SMTP_*: copy the verify URL from the dev server terminal.
• With Mailhog: set CLOUDRON_MAIL_SMTP_SERVER=localhost and CLOUDRON_MAIL_SMTP_PORT=1025 (see .env.example) and open the message at http://localhost:8025.
• Open the link in the same browser as the app (session cookie).

Optional draft sync

Postgres draft persistence via PUT /api/drafts/me is on by default for signed-in users and post-sign-in transfer of anonymous drafts. Set NEXT_PUBLIC_ENABLE_BACKEND_SYNC=false to disable server sync (anonymous progress stays in localStorage only).

Create flow

The custom wizard lives under /create/…. Step order, URLs, and Figma stage mapping are canon in docs/create-flow.md. Engineering tracking: Linear CR-89 (Done) / docs/guides/backend-linear-tickets.md Ticket 17.

Frontend & tests

• Code conventions are enforced by .cursor/rules/*.mdc — Cursor surfaces the relevant rule when editing matching files.
• See docs/testing-guide.md for testing philosophy and .cursor/rules/testing.mdc for layout/helpers.

Pull request workflow

1. Branch from main: git checkout -b feature/<short-name>.
2. Make the change and add/update tests.
3. Before merging, run docs/testing-guide.md Running tests.
4. Commit using a clear message (feat:, fix:, chore:, …).
5. Open a pull request.