App reorganization
This commit is contained in:
adilallo
+58
-33
@@ -1,51 +1,76 @@
|
||||
# Contributing
|
||||
|
||||
## Backend (local)
|
||||
## Local backend
|
||||
|
||||
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; with `SMTP_URL` unset, the **magic-link verify URL** is printed in the dev server log (see `.env.example`).
|
||||
3. Install dependencies: `npm ci`
|
||||
4. Apply migrations: `npx prisma migrate dev`
|
||||
5. (Optional) Seed curated rule templates: `npx prisma db seed` — requires `DATABASE_URL` and applied migrations. Safe to re-run; rows are upserted by `slug` so duplicates are not created.
|
||||
6. Run the app: `npm run dev`
|
||||
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 `SMTP_URL`, 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.
|
||||
|
||||
### Prisma migrations (important)
|
||||
### Prisma migrations
|
||||
|
||||
- **Do not edit** migration files that have **already been applied** to **staging, production, or any shared database**. Changing history breaks `migrate deploy` and other environments.
|
||||
- To fix a bad migration, add a **new** migration that corrects the schema. See [docs/backend-roadmap.md](docs/backend-roadmap.md) §8 for the full policy.
|
||||
- **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.
|
||||
|
||||
### API routes (overview)
|
||||
### 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 session cookie, redirect |
|
||||
| POST | `/api/auth/logout` | Clear session |
|
||||
| GET / PUT | `/api/drafts/me` | Load or save create-flow JSON (authenticated) |
|
||||
| GET / POST | `/api/rules` | List or publish rules (each **Finalize** creates a new published row until an update/edit-published API exists) |
|
||||
| GET | `/api/templates` | List curated templates |
|
||||
| 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. |
|
||||
| GET / POST | `/api/rules` | List or publish rules. |
|
||||
| GET | `/api/templates` | List curated templates. |
|
||||
|
||||
### Email magic link (sign-in)
|
||||
### Magic-link sign-in
|
||||
|
||||
- Open **[http://localhost:3000/login](http://localhost:3000/login)** or use **Log in** in the site header (modal or full page).
|
||||
- Enter email and request a link. Complete sign-in by opening the link in the **same browser** you use for the app (session cookie).
|
||||
- **No `SMTP_URL`:** the full **`GET /api/auth/magic-link/verify?...`** URL is printed in the **dev server terminal** — paste it into the browser address bar.
|
||||
- **Mailhog:** with Compose Mailhog running, set `SMTP_URL=smtp://localhost:1025` and open the link from the message in the Mailhog UI ([http://localhost:8025](http://localhost:8025)).
|
||||
|
||||
**Staging / production:** Sign-in links use the app’s origin. Ensure your reverse proxy sets **`Host`** (and TLS) so links in email match the URL users open. See [docs/backend-roadmap.md](docs/backend-roadmap.md) §9.
|
||||
- Visit **[/login](http://localhost:3000/login)** or use **Log in** in the
|
||||
site header.
|
||||
- Without `SMTP_URL`: copy the verify URL from the dev server terminal.
|
||||
- With Mailhog: set `SMTP_URL=smtp://localhost:1025` and open the message
|
||||
at [http://localhost:8025](http://localhost:8025).
|
||||
- Open the link in the **same browser** as the app (session cookie).
|
||||
|
||||
### Optional draft sync
|
||||
|
||||
Set `NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true` in `.env` so **signed-in** users can persist create-flow drafts to Postgres via **Save & Exit** and so **anonymous** progress can be **uploaded after magic-link sign-in** from the save-progress exit modal. Without it, server **PUT** `/api/drafts/me` is skipped; anonymous work stays in **browser `localStorage`**, but after sign-in with a `?syncDraft=1` return URL the app still **merges that local draft into the in-memory create flow** (no server write) so you can continue and publish.
|
||||
`NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true` enables Postgres draft persistence
|
||||
via `PUT /api/drafts/me` for signed-in users and post-sign-in upload of
|
||||
anonymous drafts. Without it, anonymous progress stays in `localStorage`
|
||||
and signed-in progress stays in memory until **Save & Exit**.
|
||||
|
||||
### Create flow URLs (custom wizard)
|
||||
### Create flow
|
||||
|
||||
The **custom** create-rule wizard lives under **`/create/…`**. The header links to **`/create`**, which redirects to the first step. **Semantic** URL segments (e.g. `community-name`, `community-size`) match Figma intent; order is **`FLOW_STEP_ORDER`** in `app/create/utils/flowSteps.ts`, with UI from **`app/create/[screenId]/page.tsx`** and **`CREATE_FLOW_SCREEN_REGISTRY`** for Figma traceability. **Figma** stages: **Create Community** (through `review`), **Create Custom CommunityRule** (`communication-methods`–`right-rail`), **Review and complete** (`confirm-stakeholders`–`completed`). **`/create/review-template/[slug]`** is a template **preview** only. Full tables and persistence are in **[docs/create-flow.md](docs/create-flow.md)**; engineering tracking: Linear **CR-89** / Ticket 17 in [docs/backend-linear-tickets.md](docs/backend-linear-tickets.md).
|
||||
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** /
|
||||
[docs/guides/backend-linear-tickets.md](docs/guides/backend-linear-tickets.md)
|
||||
Ticket 17.
|
||||
|
||||
## Frontend / tests
|
||||
## Frontend & tests
|
||||
|
||||
See [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md) and the root [README.md](README.md).
|
||||
- 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.
|
||||
|
||||
## Pull request workflow
|
||||
|
||||
1. Branch from `main`: `git checkout -b feature/<short-name>`.
|
||||
2. Make the change and add/update tests.
|
||||
3. `npm test && npm run e2e` (and `npm run storybook:build` if you touched
|
||||
stories).
|
||||
4. Commit using a clear message (`feat:`, `fix:`, `chore:`, …).
|
||||
5. Open a PR; CI runs unit, E2E, visual regression, and Lighthouse.
|
||||
|
||||
Reference in New Issue
Block a user