From 98eed6cf22c27c5a57496d2a1f96667ff8c7708b Mon Sep 17 00:00:00 2001 From: adilallo <39313955+adilallo@users.noreply.github.com> Date: Sat, 23 May 2026 16:47:47 -0600 Subject: [PATCH] Update public documenation --- CONTRIBUTING.md | 207 +++++++++++++++++++++++++++++------------------- README.md | 66 +++++++++------ 2 files changed, 168 insertions(+), 105 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57f71a0..6f0dce1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,101 +1,148 @@ # Contributing -## Local backend +Thanks for working on Community Rule. This file covers local setup, the +API surface, and the pull-request workflow. Per-file implementation +conventions live in [`.cursor/rules/`](.cursor/rules/) (auto-loaded by +Cursor); high-level orientation is in [`AGENTS.md`](AGENTS.md). -1. Copy [`.env.example`](.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` +## Local setup -Use `npx prisma studio` to inspect the database. +Prerequisites: Node **20+**, npm **10+**, Docker. -Deploying to staging or production (MEDLab Cloudron) — see -[docs/guides/ops-backend-deploy.md](docs/guides/ops-backend-deploy.md) -for the admin handoff and the linked Linear tickets for the actual -deployment-pipeline work. +```bash +cp .env.example .env # set SESSION_SECRET (≥16 chars) +docker compose up -d postgres mailhog # omit `mailhog` if you don't need + # a local inbox +npm ci +npx prisma migrate dev +npx prisma db seed # optional — seeds curated templates +npm run dev +``` -### Prisma migrations +Open [http://localhost:3000](http://localhost:3000). Use +`npx prisma studio` to browse the database. -- **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](docs/guides/backend-roadmap.md) §8. -- Any change under **`prisma/`**: run **`npm run migrate:smoke`** (see - [docs/testing-guide.md](docs/testing-guide.md#running-tests), **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.=` query params re-rank results (and may include `scores` in the JSON). See [docs/guides/template-recommendation-matrix.md](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](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. | +Deploying to staging or production (MEDLab Cloudron at `my.medlab.host`) +is documented in +[`docs/guides/ops-backend-deploy.md`](docs/guides/ops-backend-deploy.md). ### Magic-link sign-in -- Visit **[/login](http://localhost:3000/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](http://localhost:8025). -- Open the link in the **same browser** as the app (session cookie). +1. Go to [/login](http://localhost:3000/login) or click **Log in** in + the site header. +2. Submit your email. +3. Open the verify link in the **same browser** (the session cookie is + bound to that origin): + - **Without SMTP:** copy the URL from the dev-server log. + - **With Mailhog:** open the message at + [http://localhost:8025](http://localhost:8025). -### Optional draft sync +### Prisma migrations -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). +- **Never edit a migration** that has already been applied to staging, + production, or any shared database — add a new migration instead. + Full policy: [`docs/guides/backend-roadmap.md`](docs/guides/backend-roadmap.md) §8. +- **After any change under `prisma/`**, run `npm run migrate:smoke` + (Docker required). A throwaway Postgres on `127.0.0.1:5433` verifies + the migration applies cleanly. See + [`docs/testing-guide.md`](docs/testing-guide.md) → *Running tests*. + +### Draft persistence + +Signed-in create-flow drafts sync to Postgres via `PUT /api/drafts/me` +by default; anonymous progress stays in `localStorage`. Set +`NEXT_PUBLIC_ENABLE_BACKEND_SYNC=false` to disable server sync. ### Create flow The custom wizard lives under `/create/…`. Step order, URLs, and Figma -stage mapping are canon in [docs/create-flow.md](docs/create-flow.md). -Engineering tracking: Linear **CR-89** (**Done**) / -[docs/guides/backend-linear-tickets.md](docs/guides/backend-linear-tickets.md) -Ticket 17. +stage mapping are canon in +[`docs/create-flow.md`](docs/create-flow.md); component conventions are +in `.cursor/rules/create-flow.mdc`. -## Frontend & tests +## API routes -- Code conventions are enforced by `.cursor/rules/*.mdc` — Cursor surfaces - the relevant rule when editing matching files. -- See [docs/testing-guide.md](docs/testing-guide.md) for testing - philosophy and `.cursor/rules/testing.mdc` for layout/helpers. +All routes return JSON. Non-`GET` requests expect +`Content-Type: application/json` unless noted (uploads are multipart). -## Pull request workflow +### Auth & account + +| Method | Path | Purpose | +| --- | --- | --- | +| GET | `/api/health` | Liveness + DB connectivity. | +| GET | `/api/auth/session` | Current user or `null`. | +| POST | `/api/auth/magic-link/request` | Send sign-in link. | +| GET | `/api/auth/magic-link/verify` | Validate token, set cookie, redirect. | +| POST | `/api/auth/logout` | Clear session. | +| DELETE | `/api/user/me` | Delete authenticated account. | +| POST | `/api/user/email-change/request` | Send verify link to new address. | +| GET | `/api/user/email-change/verify` | Apply email change. | + +### Drafts & uploads + +| Method | Path | Purpose | +| --- | --- | --- | +| GET, PUT | `/api/drafts/me` | Load / save the signed-in create-flow draft. | +| POST | `/api/uploads` | Multipart upload (requires `UPLOAD_ROOT`). | +| GET | `/api/uploads/[id]` | Stream a previously uploaded file (public). | + +### Rules + +| Method | Path | Purpose | +| --- | --- | --- | +| GET, POST | `/api/rules` | List or publish rules. | +| GET | `/api/rules/me` | Owner's published rules. | +| GET, PATCH, DELETE | `/api/rules/[id]` | Public read; owner update / delete. | +| POST | `/api/rules/[id]/duplicate` | Owner clone. | +| GET, POST | `/api/rules/[id]/stakeholders` | List / invite stakeholders. | +| DELETE | `/api/rules/[id]/stakeholders/[stakeholderId]` | Remove stakeholder. | +| POST | `/api/rules/[id]/stakeholders/[stakeholderId]/resend` | Resend invite email. | +| GET | `/api/invites/rule-stakeholder/verify` | Verify stakeholder invite token. | + +### Templates & create-flow catalog + +| Method | Path | Purpose | +| --- | --- | --- | +| GET | `/api/templates` | List curated templates. Repeatable `facet.=` query params re-rank results. | +| GET | `/api/templates/[slug]` | Single template with normalized `{ section, slug }` composition. | +| GET | `/api/create-flow/methods` | Built-in governance methods / core values for the wizard. Required `section` query param. | + +Facet semantics and the recommendation matrix: +[`docs/guides/template-recommendation-matrix.md`](docs/guides/template-recommendation-matrix.md) +§9. + +### Misc + +| Method | Path | Purpose | +| --- | --- | --- | +| POST | `/api/organizer-inquiry` | "Ask an organizer" form submission. | +| POST | `/api/use-cases/[slug]/duplicate` | Duplicate a use-case demo rule. | +| GET, POST | `/api/web-vitals` | Read / ingest web vitals. Storage mode set by `WEB_VITALS_STORAGE` (`local` in dev, `external` in prod). | + +## Testing + +The full testing recipe and philosophy live in +[`docs/testing-guide.md`](docs/testing-guide.md). Component conventions +and shared helpers are in `.cursor/rules/testing.mdc`. + +A typical pre-merge subset: + +```bash +npx tsc --noEmit +npm run knip +npm test +npx next build +``` + +Add `npm run e2e` for routing, auth, or critical-flow changes, and +`npm run migrate:smoke` for anything under `prisma/`. + +## Pull-request workflow 1. Branch from `main`: `git checkout -b feature/`. -2. Make the change and add/update tests. -3. Before merging, run [docs/testing-guide.md](docs/testing-guide.md#running-tests) *Running tests*. -4. Commit using a clear message (`feat:`, `fix:`, `chore:`, …). -5. Open a pull request. +2. Make the change and add or update tests. +3. Run the relevant subset of the testing recipe above. +4. Commit using a conventional-commit prefix: `feat:`, `fix:`, + `chore:`, `docs:`, `refactor:`, `test:`. +5. Open a pull request; link the Linear ticket if there is one (e.g. + `CR-123`). diff --git a/README.md b/README.md index 6ada988..318ecb6 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,82 @@ # Community Rule A Next.js application for community decision-making and governance -documentation. +documentation — author, browse, and share governance "rules" built from +curated templates and a guided wizard. + +Live at [communityrule.info](https://communityrule.info). Packaged as a +Cloudron app for MEDLab; see +[docs/guides/ops-backend-deploy.md](docs/guides/ops-backend-deploy.md) +for the deployment handoff. ## Requirements - Node.js **20+** (LTS) - npm **10+** +- Docker (for local Postgres and Mailhog) -## Getting started +## Quick start ```bash +cp .env.example .env # then set SESSION_SECRET (≥16 chars) +docker compose up -d postgres # add `mailhog` for a local inbox npm ci +npx prisma migrate dev npm run dev ``` -Open [http://localhost:3000](http://localhost:3000). +Open [http://localhost:3000](http://localhost:3000). Without +`CLOUDRON_MAIL_SMTP_*` set, magic-link sign-in URLs are printed to the +dev-server log instead of emailed. -Backend setup (Postgres, Prisma, magic-link auth) is documented in +Full local backend, API reference, and PR workflow: [CONTRIBUTING.md](CONTRIBUTING.md). -## Common scripts +## Scripts | Command | What it does | | --- | --- | | `npm run dev` | Next.js dev server (Turbopack). | | `npm run build` / `npm start` | Production build / serve. | | `npm test` | Vitest unit + component tests with coverage. | -| `npm run test:component` | Faster inner loop — components only. | +| `npm run test:component` | Components only — faster inner loop. | | `npm run e2e` | Playwright E2E + visual regression. | +| `npm run migrate:smoke` | Throwaway Postgres + `prisma migrate deploy` (Docker required). | | `npm run storybook` | Storybook on port 6006. | +| `npm run knip` | Detect unused files / exports. | | `npm run lhci` | Lighthouse CI performance pass. | +See [`package.json`](package.json) for the full list (visual regression, +bundle analysis, seeding, etc.). + ## Project layout ```text -app/ Next.js app router: route groups (marketing), (app), (admin), (dev); - shared components under app/components/; optional _components/ - colocated with a route (e.g. (admin)/monitor/_components/) -lib/ Shared library code (i18n, validation, utilities) -messages/en/ Localized UI copy (see docs/guides/i18n-translation-workflow.md) -prisma/ Database schema, migrations, seed -public/ Static assets -stories/ Storybook stories -tests/ Vitest + Playwright suites -docs/ User-facing documentation (start with docs/README.md) -.cursor/rules/ Implementation conventions enforced by Cursor +app/ Next.js app router — route groups (marketing), (app), + (admin), (dev); shared components under app/components/; + admin-only widgets under app/(admin)//_components/ +lib/ Shared library code (server, validation, create-flow logic) +prisma/ Schema, migrations, seed +messages/en/ Localized UI copy (single-locale today; English) +public/ Static assets +stories/ Storybook stories +tests/ Vitest + Playwright suites (mirror source paths) +docs/ Human-facing documentation — start at docs/README.md +.cursor/rules/ Per-file conventions (auto-loaded by Cursor) +scripts/ Build, release, and smoke-test scripts ``` ## Tech stack -Next.js 16 · React 19 · TypeScript · Tailwind CSS 4 · Prisma · Vitest · -Playwright · Storybook 10 · Lighthouse CI. +Next.js 16 · React 19 · TypeScript · Tailwind CSS 4 · Prisma 6 · +PostgreSQL · Vitest · Playwright · Storybook 10 · Lighthouse CI. ## Documentation - [docs/README.md](docs/README.md) — index of guides and rules. - [docs/create-flow.md](docs/create-flow.md) — create-rule wizard canon. - [docs/testing-guide.md](docs/testing-guide.md) — testing philosophy. -- [CONTRIBUTING.md](CONTRIBUTING.md) — local backend, API routes, PR - workflow. - -## License - -[MIT](LICENSE). +- [docs/guides/ops-backend-deploy.md](docs/guides/ops-backend-deploy.md) + — Cloudron deploy + cutover plan. +- [CONTRIBUTING.md](CONTRIBUTING.md) — local backend, API routes, PR workflow. +- [AGENTS.md](AGENTS.md) — orientation for AI coding agents.