CommunityRule/community-rule
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update public documenation

Browse Source
This commit is contained in:
adilallo
2026-05-23 16:47:47 -06:00
parent ca338cb017
commit 98eed6cf22
2 changed files with 168 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+127 -80
View File
@@ -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.<group>=<value>` 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.<group>=<value>` 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/<short-name>`.
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`).
README.md
+41 -25
View File
@@ -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)/<route>/_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.