Session lifecycle, public rules API, web vitals RUM, ops docs, and project guidelines #47

2026-04-24T00:30:49Z

an.di commented

2026-04-24 00:30:49 +00:00

Overview

This PR continues backend and platform work: a clearer API error contract and shared helpers (apiRoute, requestId, response helpers), custom session lifecycle across auth routes (magic link, session, logout, drafts), a public marketing rule detail page and related rules API behavior, and web vitals changes that favor external RUM with a refactored admin monitor dashboard and local storage plumbing where appropriate. It also adds operational documentation (Cloudron/backend deploy), CI for a Postgres migration smoke job, a session prune script, and a repo-wide Cursor rule (Karpathy-style coding guidelines) plus a small api-routes rule update. Docs (backend tickets, roadmap, relaunch brief) are refreshed to match the current plan.

Changes

Auth & session: Magic link verify/request, session, logout, and drafts/me updated for consistent session handling; lib/server/session.ts and scripts/prune-sessions.ts for lifecycle maintenance.
API layer: lib/server/apiRoute.ts, requestId, extended responses.ts for structured errors; rules and drafts routes aligned; app/api/web-vitals/route.ts and validation/store/mode under lib/server/webVitals/.
Product: app/(marketing)/rules/[id]/page.tsx for public rule detail; lib/server/publishedRules.ts and related API routes.
Admin: MonitorPageContent split from monitor page; Web Vitals dashboard container/types/view and message files updated.
Config & env: .env.example updates for new/related settings.
CI: .gitea/workflows/migrate-smoke.yaml for migration smoke against Postgres.
Docs: docs/guides/ops-backend-deploy.md (new), updates to backend-linear-tickets, backend-roadmap, docs/relaunch-brief.md, docs/README.md, CONTRIBUTING.md.
Project rules: .cursor/rules/coding-guidelines.mdc (always-apply behavioral guidelines); .cursor/rules/api-routes.mdc updated.
Tests: New/expanded unit tests for apiRoute, requestId, responses, draftsMe, rulesById, session lifecycle, web vitals schema/mode, etc.

Screenshots

How to Test

Install & env: From repo root, follow CONTRIBUTING.md; copy .env.example → .env and set values needed for auth, DB, and web vitals as documented.
Quality bar (CI parity):
npx tsc --noEmit
npx vitest run
npx next build
Spot-check: Log in via magic link; confirm session behavior and drafts/me; open a published rule on the marketing rule detail URL; in admin, open Monitor and confirm Web Vitals dashboard behavior and copy (no hardcoded user-visible strings outside messages/).
If you use Gitea CI: Confirm the new migration smoke workflow is appropriate for your DB credentials/secrets.

Notes

Branch name suggests this is one in a series (BackendImplementation5); call out if this should merge before/after related backend tickets.
Web vitals path now emphasizes external RUM; local file store/mode are implementation details for ops—document any required env in deploy notes.
Cursor users get coding-guidelines.mdc automatically (alwaysApply: true); no change to AGENTS.md unless you want it cross-linked.
Known follow-ups: Anything still gated by NEXT_PUBLIC_ENABLE_BACKEND_SYNC or legacy create-flow scaffolding remains per existing project policy (do not remove without an explicit request).

## Overview This PR continues backend and platform work: a clearer **API error contract** and shared helpers (`apiRoute`, `requestId`, response helpers), **custom session lifecycle** across auth routes (magic link, session, logout, drafts), a **public marketing rule detail page** and related **rules API** behavior, and **web vitals** changes that favor **external RUM** with a refactored admin monitor dashboard and local storage plumbing where appropriate. It also adds **operational documentation** (Cloudron/backend deploy), **CI** for a Postgres **migration smoke** job, a **session prune** script, and a repo-wide **Cursor rule** (Karpathy-style coding guidelines) plus a small **api-routes** rule update. **Docs** (backend tickets, roadmap, relaunch brief) are refreshed to match the current plan. ## Changes - **Auth & session:** Magic link verify/request, session, logout, and `drafts/me` updated for consistent session handling; `lib/server/session.ts` and `scripts/prune-sessions.ts` for lifecycle maintenance. - **API layer:** `lib/server/apiRoute.ts`, `requestId`, extended `responses.ts` for structured errors; rules and drafts routes aligned; `app/api/web-vitals/route.ts` and validation/store/mode under `lib/server/webVitals/`. - **Product:** `app/(marketing)/rules/[id]/page.tsx` for public rule detail; `lib/server/publishedRules.ts` and related API routes. - **Admin:** `MonitorPageContent` split from monitor page; Web Vitals dashboard container/types/view and message files updated. - **Config & env:** `.env.example` updates for new/related settings. - **CI:** `.gitea/workflows/migrate-smoke.yaml` for migration smoke against Postgres. - **Docs:** `docs/guides/ops-backend-deploy.md` (new), updates to `backend-linear-tickets`, `backend-roadmap`, `docs/relaunch-brief.md`, `docs/README.md`, `CONTRIBUTING.md`. - **Project rules:** `.cursor/rules/coding-guidelines.mdc` (always-apply behavioral guidelines); `.cursor/rules/api-routes.mdc` updated. - **Tests:** New/expanded unit tests for `apiRoute`, `requestId`, `responses`, `draftsMe`, `rulesById`, session lifecycle, web vitals schema/mode, etc. ## Screenshots <img width="601" alt="Screenshot 2026-04-23 at 6.30.28 PM.png" src="attachments/7d33768f-109e-4bb5-9056-246d4b5fd627"> ## How to Test 1. **Install & env:** From repo root, follow `CONTRIBUTING.md`; copy `.env.example` → `.env` and set values needed for auth, DB, and web vitals as documented. 2. **Quality bar (CI parity):** `npx tsc --noEmit` `npx vitest run` `npx next build` 3. **Spot-check:** Log in via magic link; confirm session behavior and `drafts/me`; open a published rule on the marketing rule detail URL; in admin, open **Monitor** and confirm Web Vitals dashboard behavior and copy (no hardcoded user-visible strings outside `messages/`). 4. **If you use Gitea CI:** Confirm the new migration smoke workflow is appropriate for your DB credentials/secrets. ## Notes - Branch name suggests this is one in a series (`BackendImplementation5`); call out if this should merge before/after related backend tickets. - **Web vitals** path now emphasizes external RUM; local file store/mode are implementation details for ops—document any required env in deploy notes. - **Cursor** users get `coding-guidelines.mdc` automatically (`alwaysApply: true`); no change to `AGENTS.md` unless you want it cross-linked. - **Known follow-ups:** Anything still gated by `NEXT_PUBLIC_ENABLE_BACKEND_SYNC` or legacy create-flow scaffolding remains per existing project policy (do not remove without an explicit request).

Screenshot 2026-04-23 at 6.30.28 PM.png

175 KiB

an.di added 8 commits 2026-04-24 00:30:50 +00:00

Web vitals: prefer external RUM 2d58887a15

Public rule and detail page added 0e7a57052b

CI: Postgres migration smoke c7f22a0990

Cloudron deployment plan 4d066dad0e

API error contract 5457d3554b

Custom session lifecycle 208ddfb8ca

Update docs 56da6d21ea

Add coding guidelines

Migrate Smoke / migrate (pull_request) Has been cancelled