Instruction file imported from arcanewords-app/arcane-reader (.cursor/rules/routing.mdc). Copyright stays with the author.

Routing (Canonical)

Sync policy

• This file is the source of truth for the route map.
• Implementations: @src/client/AppRouter.tsx (frontend), @src/server.ts (API).
• docs/ROUTES.md is a GitHub-friendly stub; do not edit it instead of this file.

When changing routes

• Update tables below (path, method/access, description).
• Update navigation flow if user journey changed.
• Change code in the same PR: client + server + this rule.
• Remove stale rows when endpoints are deleted.

Verification

• New route exists in code and in this file with identical path.
• Renames updated in client, server, and this file.

Frontend Routes (Client)

Defined in src/client/AppRouter.tsx.

Reading mode URL sync

See also @.cursor/rules/spa-navigation.mdc for the general SPA policy (push vs replace, path vs query, PR checklist).

• Chapter navigation (next/prev, TOC, keyboard): ReadingMode calls preact-router route() to update :chapterId in the path (history push). No full page reload.
• Browser Back/Forward: initialChapterId from URL drives currentChapterIndex; cached chapter text stays in component state.
• Share / F5: URL reflects the chapter being read.
• Author exit: returns to chapter editor for the current chapter (not the entry URL).
• Scroll position within chapter: optional ?paragraph= in URL for share/deep links only. Server paragraph bookmark deferred (see ADR reading-progress-watermark).

Access Levels

• guest+ - anyone (including unauthenticated)
• user+ - requires role: user or higher (guest redirects to /?login=required)
• author+ - requires role: author or higher (user sees UpgradeScreen on /translation-requests and /projects/*)
• admin+ - requires role: admin (non-admin users see access denied)

Protected routes

When guest visits /profile, /translation-requests, /projects, /projects/*, /admin/entities, or /admin/*, redirect to /?login=required and open AuthModal.

API Routes (Server)

Defined in src/server.ts.

Validation (Zod)

Most API endpoints validate request body and query parameters using Zod schemas from src/api/schemas/. On validation failure, the API returns 400 with:

{
  "error": "Validation failed",
  "details": { "fieldName": ["error message"] }
}

Auth

System

Circuit breaker (503): requireHealthySupabase blocks mutating and private routes when Supabase is down (Redis cache outages do not trip the breaker). Shared health is stored in Redis (system:health, 60s TTL) so warm serverless instances agree. Exempt: /api/status, /api/health, and public read-only GET: /api/news, /api/news/*, /api/announcements/active, /api/publications, /api/publications/*, /api/public/entities, /api/public/entities/*.

Debug (dev only, NODE_ENV !== production)

Vite dev proxy: /debug → debug app port 5174. See @docs/02-how-to/debug-translation.md and @.cursor/rules/debug.mdc.

Prompt Lab (dev only, NODE_ENV !== production)

Vite dev proxy: /prompt-lab → port 5175. See @docs/02-how-to/prompt-lab.md and @.cursor/rules/prompt-lab.mdc.

User (requireAuth)

Translation request board (requireAuth + requireRole('author'))

POST /api/projects body may include catalogTranslationRequestId and translatorEntityId to prefill from a request and link interest.

Projects (requireAuth + requireRole('author'))

Glossary (requireAuth + requireRole('author'))

Admin (requireAuth + requireRole('admin'))

News & announcements (public)

Cache invalidation notes

• Mutation endpoints in projects, chapters, glossary, cover/metadata, publish, and admin/news flows invalidate Redis-backed caches for:
  • public metadata entities (/api/public/entities) after admin create,
  • news list/post and active announcements after admin news/alert mutations,
  • user project views (/api/projects, /api/projects/:id, summaries),
  • publication pages (/api/publications/*) when relevant,
  • user reading/token aggregates where relevant.
• This prevents stale UI after successful write operations.

Cover & Metadata (requireAuth + requireRole('author'))

Export

Publications (public)

Public metadata entities (public)

Publish (requireAuth + requireRole('author'))

Translation Reports (requireAuth + requireRole('author'))

SPA fallback

SEO (SSR, sitemap, canonical)

Implemented in src/server.ts. Audits: .cursor/skills/seo/SKILL.md, .cursor/rules/seo.mdc.

Crawl files

Sitemap contents and limits

• / (priority 1.0) plus static: /about, /contact, /privacy, /terms, /catalog, /news, /account-tiers
• Each published publication: /p/{slugOrId} (up to 1000 from listPublicationsPublic)
• First translated chapter reading URL for at most 100 publications (SITEMAP_CHAPTER_PUBS_LIMIT)
• Published news posts: /news/{slugOrId} (up to 100, SITEMAP_NEWS_LIMIT)

SSR HTML (meta for crawlers)

Client navigation updates head via usePageMeta.ts (publications, news detail) and useStaticPageMeta.ts (static info pages); direct loads and bots rely on SSR above.

Vercel rewrites

In vercel.json, /, /catalog, /about, /contact, /privacy, /terms, /news, /news/:slug*, /account-tiers, and /p/* route to api/index (Express SSR). Other SPA paths fall through to static index.html.

Shared SEO modules

• src/shared/robotsTxt.ts — buildRobotsTxt for Express and api/robots.ts
• src/shared/staticPageMeta.ts — static page titles/descriptions for SSR and client

Auth areas

/projects/*, /profile, /translation-requests, /admin/* are disallowed in robots and not in sitemap (author workspace, not public SEO targets).

Navigation Map (Key Flows)

User journey tables (header, catalog, projects, publication): @docs/_canonical/rules/routing-nav.md.

Token Usage

Token usage indicator is shown only on paths where it's relevant. See src/client/utils/tokenUsagePaths.ts:

• /projects - projects grid
• /projects/:id - project page (except /reading)

Monorepo apps (not arcane-reader)

Web scraper

Moved to standalone repo arcane-scraper (@arcane/scraper + @arcane/scraper-console). Not registered in arcane-reader src/server.ts.

Async Jobs (BullMQ Worker)

Async analysis and translate jobs require a separate Worker process and Redis (REDIS_URL).

• Local dev: npm run dev:full — API, client, and worker against Docker Postgres; or run npm run worker in a separate terminal. Live prod DB: npm run dev:full:prod (.env.prod.local).
• Production: npm run start:worker - run alongside npm run start (API).
• Queues: chapter-analysis, chapter-translate. One active job per user per type (analysis/translate).

Related Files

• src/client/AppRouter.tsx - frontend routes
• src/client/components/Auth/AdminGate.tsx - admin role gate
• src/server.ts - API routes
• src/api/routes/index.ts - registers route modules (chapters.ts, chapterImport.ts, chapterReports.ts, …)
• src/worker.ts - BullMQ worker entry point
• src/services/chapterQueue.ts - BullMQ queues (analysis, translate)
• src/middleware/auth.ts - requireAuth, optionalAuth, requireRole
• src/client/components/Auth/AuthorGate.tsx - author+ role gate
• src/client/pages/AdminEntitiesPage.tsx - admin entities page
• src/client/utils/tokenUsagePaths.ts - token usage display paths