QuranFlow Admin · team update
Six days since the May 20 meeting asks, the production handover is shipped. The Granjur engineering team gets a single email link that points to the onboarding site, the new production repo, the locked stack, and the 18 ADRs. This page is the recap for the AlMaghrib team — what shipped, what was decided, and what's next.
TL;DR
1. Production repo created at almaghrib-engineering/quranflow-admin — the scaffold Granjur will build on. 18 ADRs, 11 domain narratives, 56 screen bindings, four-contract documentation model.
2. Onboarding mini-site live at quranflow-admin-onboarding.pages.dev — one shareable link with the 30-minute visual walkthrough, the HANDOFF cover letter, the tech-stack summary, and the day-1 reading path.
3. Backend host decided: DigitalOcean App Platform (region nyc) — ADR-019. Supersedes the original Fly.io recommendation after Wasif's head-to-head review.
4. Issue routing in place — four GitHub issue templates, all default-tagging @Kamran-AM + @LejlaPi. Every spec question reaches both of us.
§1
A new private repo lives at almaghrib-engineering/quranflow-admin. It is the production codebase Granjur builds against; the mockup repo stays the visual contract. Granjur owns engineering commits from this point; we own the spec, the locked stack, and the ADR layer.
Visual / Schema / API / Decisions
The build is partitioned across four contracts that lock together. The mockup is the visual contract. The Drizzle schema is the database contract. The tRPC routers are the API contract. The 18 ADRs in docs/spec/decisions/ are the decision contract. Granjur reads in that direction; we author in reverse (a new requirement starts as an ADR and flows down to the visual).
/spec, /locked-check, /pre-pr, /verify-phase, /visual-check, /why, plus /file-issue (interactive issue filing)Five things Granjur owns from day 1 — pre-authoring would have constrained their engineering judgement:
drizzle-kit generate is their first Week-1 task)Plus five database tables that are designed but not yet in Drizzle TS code — payment_setup_attempts, system_locks, stripe_sync_runs, billing_webhook_dead_letter, billing_alerts_archive. Schema doc §1.4 lists them; Granjur ships these in Phase 4-5 before the consumer code lands.
§2
One Cloudflare Pages site bundles everything Granjur needs on day 1. The intent is: send one link in the kickoff email and the engineering team can self-orient before our first call.
Live onboarding site
quranflow-admin-onboarding.pages.dev
Landing page with Assalamu alaikum greeting, numbered 1→5 reading path (Handoff → Walkthrough → Tech stack → README → CLAUDE.md), and a reference section for the Reading order and Recommended plugins docs.
§3
The original architecture research recommended Fly.io in the LHR (London) region. Two issues surfaced in the May 2 stakeholder review: Fly.io was lightly justified (never scored against alternatives), and the region was wrong for a USA + Canada customer base. Both questions collapsed into one host pick.
DigitalOcean App Platform, region nyc
Wasif (Granjur engineering) ran a head-to-head Render vs Railway vs DigitalOcean App Platform matrix. All three support always-on Node.js, persistent connections (for SSE + Postgres LISTEN/NOTIFY), native scheduled jobs, and US East regions at similar pricing (~$22-27/month). Kamran accepted the recommendation on the lowest-vendor-risk branch.
The rest of the stack does not change. Neon Postgres (us-east-2, co-located with DigitalOcean nyc for sub-10ms DB latency), Hono on the backend, R2 for file storage, Better Auth, Drizzle, tRPC. Full options matrix is in ADR-019.
Database — Neon Postgres (us-east-2)
Backend host — DigitalOcean App Platform (nyc)
Backend framework — Hono
API — tRPC v11
ORM — Drizzle
Auth — Better Auth (5-role)
Frontend host — Cloudflare Pages
Frontend framework — Vite + React 19 + TanStack Router
Server state — TanStack Query
Styling — Tailwind v4 + shadcn/ui
Email — Resend + React Email
File storage — Cloudflare R2
Monitoring — Sentry
Runtime + tests — Bun + bun:test
Each entry is contractual — substitution requires a new ADR. Excluded library families are listed in CLAUDE.md §4 (no Prisma, no NextAuth, no Express/Fastify, no Zustand/Redux, no CSS-in-JS, no Vitest/Jest).
§4
The bundle has ~30 open spec questions Granjur will hit during implementation (OQ codes in the communication domain, TBDs in scheduling, "Open Questions" sections in 4 of 11 domain narratives). Each one needs routing. We've put four issue templates in place that auto-tag the right people, and a Claude Code skill that walks engineers through filing them.
| Template | When to use |
|---|---|
| 🔎 Open spec question | A TBD or OQ code in docs/spec/ — e.g. OQ-C8 (attachment scope), SQ13 (countdown timezone) |
| 🏗️ Architecture proposal | A change to the LOCKED stack, schema, or auth (likely needs an ADR) |
| 💳 Billing / Stripe decision | Documenting a billing or Stripe-side decision made during implementation |
| 🚀 Infra / deployment | Vendor signups, hosting, DNS, scaling, CI/CD |
All four routes default to @Kamran-AM + @LejlaPi. Kamran loops in Wasif (infra) or Usama (Stripe ratification) when their input is needed. Lejla sees every product and spec question, by default.
Engineers using Claude Code can run /file-issue for an interactive flow. The skill walks through:
gh issue create with the right assignees + labelsThe intent is consistent, focused, high-quality issues that don't require follow-up clarification rounds.
§5
Three things in the immediate pipeline.
60-minute structure walkthrough
Single video call covering the bundle tour, the four-contract model in practice, the Week-0 exit-gate run, and Phase-0 issue assignments. Kamran joins from EST timezone; the Granjur team proposes a window. Recording lets future engineers onboard without re-running.
Vendor signups
Five vendors to sign up for: Neon Postgres, DigitalOcean App Platform, Cloudflare R2, Resend, Sentry. Each has a Phase-0 issue stub in docs/issues/phase-0/ with the steps. None of these are coding tasks — they unblock everything else.
Schema + Auth + first 5 screens
Drizzle migrations deployed to Neon. Better Auth signup/signin flow working with the 5-role access-control plugin. First five screens rendered with seeded data: Dashboard, Students list, Student Detail (Profile tab), Settings, Auth pages. From there, the roadmap is in docs/architecture/roadmap.md — 12 weeks total.