اكتشف بثقة. ابنِ بإتقان. شارك بمسؤولية. The directory and distribution hub for Quranic software resources.
Production: https://ratq.itqan.dev · Beta: https://beta.ratq.itqan.dev
- App: Next.js 15 serving a client-side
react-router-domapp (app/[[...slug]]catch-all, routes insrc/router.tsx), React 18, TypeScript, Tailwind CSS 3, RTL-first,i18next(Arabic default, English). - State/data: TanStack Query, Zustand.
- Backend: the Payload CMS API in
payload-backend/(Users, Resources, Comments, AccessRequests, APIKeys, Reports, Notifications, Announcements). The frontend only calls its REST API; no other backend. - Hosting: Cloudflare Pages (project
ratq-beta), built by Cloudflare frommainwith@cloudflare/next-on-pages. A second Pages project builds the beta site from thebetabranch withNEXT_PUBLIC_BETA=1. Every dynamic route must exportruntime = 'edge'. The API is deployed separately (see.github/workflows/deploy-backend.yml). - Tests: Vitest + Testing Library (unit), Playwright (
e2e/).
NEXT_PUBLIC_PAYLOAD_API_URL is read at build time.
- Set (production, beta): live mode. Resources, auth, comments, access requests, API keys, reports and notifications use the real API. Pages with no backend yet are marked Demo / تجريبي in the nav and run on in-memory mock data.
- Unset (default local build): everything runs on mock data, no backend needed.
PORTING.md maps every live route to its page; MOCKED.md lists the Demo-only pages that still need a backend.
Requires Node 20+ and pnpm 10+.
pnpm install
pnpm dev # mock mode, http://localhost:3000To develop against a local Payload, start payload-backend/ (see its README; its dev server also uses port 3000) and run the frontend on another port:
NEXT_PUBLIC_PAYLOAD_API_URL=http://localhost:3000/api pnpm exec next dev -p 3100The production API only allows the ratq.itqan.dev and beta.ratq.itqan.dev origins, so localhost cannot call it.
pnpm typecheck
pnpm test # Vitest
pnpm pages:build # next-on-pages build (what Cloudflare runs), output in .vercel/output/static
pnpm test:e2e # Playwright against beta (BASE_URL overrides)pnpm test:e2e runs read-only specs by default. The sign-in spec needs a throwaway account in E2E_EMAIL / E2E_PASSWORD and is skipped without them. Never use a real user.
main is the live site and beta is the beta site. Work lands on beta first and is promoted with a pull request from beta into main. A build with NEXT_PUBLIC_BETA set refuses to run on main.
Pushing to either branch deploys by itself: the Cloudflare Pages project builds with npx --yes --legacy-peer-deps @cloudflare/next-on-pages@1 and serves .vercel/output/static, so no GitHub Actions minutes are used. Pull requests get a preview URL from the same project. .env.production (committed, public URLs only) points the build at the live APIs. To try the build locally:
pnpm pages:build
pnpm pages:dev # serves .vercel/output/static on http://localhost:8788Roll back from the Cloudflare dashboard (Pages, ratq-beta, Deployments, Rollback).
See CONTRIBUTING.md and our CODE_OF_CONDUCT.md. Features marked Demo are the best places to start. All contributions target the beta branch.
Every merged contribution gets a shoutout on the Contributors page and the community's Hall of Fame. Pick up a good first issue and join them.
- RATQ Community Platform overview: strategic overview and roadmap.
Questions or design discussions: GitHub Discussions. Notable changes are in CHANGELOG.md.
Content rules for Quranic text are in DECISIONS.md, GOVERNANCE.md and SECURITY.md.