QuranFlow Admin Redesign

Before you can redesign a system, you have to understand everything it does. Not what people say it does — what it actually does, screen by screen, field by field.

The QuranFlow admin backend has 35+ screens spread across 9 navigation sections, backed by 10 database tables and integrations with Stripe (payments), Vimeo (video hosting), and InfusionSoft (email automation). Every screen was documented: what data it shows, what actions it supports, what business rules it enforces.

The capability map revealed a structural pattern: the backend is organized by data type. There's a "Students" section, a "Semesters" section, a "Program" section. Each maps to a database table. This seems logical — until you try to actually use it.

The capability map documented the system. The interview revealed how it fails.

The admin — the primary power user who manages students, semesters, billing, and content daily — walked through her real workflows. Five pain points emerged:

1. Semester setup is entirely manual. Content must be re-uploaded from scratch every semester. 19+ screens, 50-80 clicks, 3 external tools.
2. Billing has zero presence in the backend. All payment data — subscriptions, family plans, scholarships, deferments — lives in Google Sheets and Stripe. Support staff can't answer basic billing questions without escalating.
3. Student deactivation is disconnected from payment cancellation. Two steps, two systems, no link between them.
4. The dashboard provides no actionable information. It shows passive stats. No alerts, no failed payments, no TA response times.
5. Navigation is organized by data type, but the admin thinks in domains of responsibility.

That last point was the critical reframe. When asked how she'd organize the backend, her answer wasn't "Students, Lessons, Reports" (the current structure). It was:

Student Management, Semester Management, Content, Scheduling, Teacher Management, Reporting, and Miscellaneous.

She doesn't think in database tables. She thinks in areas of responsibility. The current navigation forces her mental model into a structure that doesn't match how she works — which is why single workflows span 5-9 screens across multiple sections.

The interview revealed two distinct problems that need different research methods:

Navigation — Which organizational principle should govern the backend? This requires framework analysis: study different ways to organize admin tools, map real workflows through each option, score them, pick a winner. It's a design problem.

Billing — What billing data exists, where does it live, and what would it take to bring it into the admin backend? This requires technical discovery: audit code repositories, analyze Stripe's API, document every Google Sheet workaround. It's a research problem.

These problems are independent. Navigation research doesn't need billing data, and billing discovery doesn't need navigation decisions. So we split into two parallel workstreams that converge when both are complete.

This is a theme in AI-assisted product work: you can't just ask the AI to "redesign the admin backend." The problem is too large and too ambiguous. You have to decompose it into structured phases, each with a defined input, methodology, and deliverable. The next five steps are those phases.

There are fundamentally different ways to organize an admin backend. The current system uses one (organize by data type). But there are at least five others, each with different assumptions about how the admin thinks and works. Before choosing, we analyzed all six:

Each framework was analyzed against the admin's interview data: what assumptions does it make about how the admin thinks? What does it do well? Where does it break down?

In parallel, we mapped six real admin workflows step-by-step through the current system. This produced the baseline data every candidate would be measured against:

The numbers made the problem concrete. Semester setup alone: 19 screens, 50-80 clicks, 3 external tools. Any candidate that doesn't dramatically reduce these numbers isn't worth building.

With workflow evidence, three frameworks were eliminated as standalone navigation paradigms. Not because they're bad ideas — because each has a structural flaw that disqualifies it as the primary organizing principle:

• Object-Based eliminated — it's the current system, and it's the problem. Scored lowest on mental model match (2/5). The admin explicitly rejected it.
• Workflow-Based eliminated — guided wizards constrain power users. Edge cases (which the admin deals with constantly) break codified flows.
• Phase-Based eliminated — semester phases overlap in practice. A nav that changes by phase confuses TAs who log in irregularly.

But elimination doesn't mean discarding their best ideas. From each eliminated framework, we borrowed specific features that every surviving candidate must include:

• From Workflow: a semester setup checklist and a gated close workflow (payment setup blocked until promotions are complete)
• From Phase: phase-aware dashboard prompts ("semester close approaching — 4 items need attention")

The three survivors became three hybrid candidates, each specified down to the screen level — complete navigation trees, screen placement maps for all 35 existing screens, new screens introduced:

A navigation design can look good on paper and fail in practice. The only way to know: walk real workflows through it. Every workflow from Step 4 was traced through every candidate — exact screen paths, click counts, information co-location, external tool dependencies.

The results:

Enhanced Candidate A won. Domain-first navigation matching how the admin actually thinks, augmented with the strongest ideas from the other two:

• From B: an operational dashboard with configurable alert tiles and phase-aware prompts
• From C: global search resolving to entity pages from any screen

The projected improvements across all 6 workflows:

While Workstream 1 solved how to organize the backend, Workstream 2 tackled the system's biggest missing capability: billing has zero presence in the admin interface.

The admin manages payments weekly — but entirely outside the backend. Five code repositories were audited to understand what billing infrastructure exists. The checkout pipeline was traced end-to-end: frontend checkout → webhook processing → Stripe subscription creation → and then... nothing. Subscription data flows into Stripe and stays there. The admin backend never reads it.

Every Google Sheet workaround was documented:

Stripe's API was analyzed for what data could surface in the admin backend. The finding: Stripe has everything — subscription status, payment history, failure reasons, coupon redemptions. The data exists. It just isn't visible.

Six new billing screens were defined: Payment Overview, Payment Plans (enhanced), Coupons (enhanced), Family Plans, Scholarships & Deferments, plus billing tabs on student and semester entity pages.

The two workstreams converged. Enhanced Candidate A provided the 8+1 domain navigation structure. Billing discovery provided the requirements for six new billing screens plus entity-level payment tabs. The result: a complete, mockup-ready specification.

Each of the 11 spec files is detailed enough to build from without asking clarifying questions: every column, filter, action, state, role-based visibility rule, and data source for every screen.

The three most specified areas — each required the depth of a mini-application:

• Student Detail Page: 6 tabs consolidating what currently requires 5-7 screens. The profile the admin asked for in the interview — "level, TA, gender, semester history, submission count, and payment status on one screen."
• Semester Hub: 4 tabs including a gated Close Workflow that blocks payment setup until promotions are complete — directly solving the admin's most dangerous pain point.
• Billing & Payments: 6 screens bringing Stripe data into the admin backend for the first time, plus entity-level tabs so payment status appears in context.

The specification was translated into a working interactive prototype.

Built in 13 phases, each producing committed, navigable screens. Complex screens first (Student Detail, Semester Hub Close Workflow, Billing) — they set patterns that simpler screens follow. Six independent content screens were built in parallel. Stripe's admin UI served as the design reference: data-dense tables, inline status badges, metric cards with trends.

After the initial build, every screen was audited line-by-line against its specification. 52 deviations found — missing columns, incorrect filters, wrong badge colors, absent empty states. 44 resolved across four batches. This is the work that separates a demo from a specification-accurate prototype: ensuring that what you see matches what the spec says, so that future engineering decisions can reference the mockup with confidence.

The three screens that demonstrate the redesign's impact:

• Dashboard: Seven alert tiles (failed payments, pending submissions, TA response times, appointment utilization, semester phase status, app issues, student snapshot) replace what was a page of passive statistics. The admin's daily monitoring workflow drops from 4-5 screens with 3 external tools to one screen with zero external tools.
• Student Detail Page: One entity page with six tabs replaces the current 5-7 screen workflow for handling a student support issue. Profile, submissions, payments (from Stripe), appointments, semester history, and actions — all on one page. The consolidated student profile the admin asked for in the interview, built exactly as described.
• Semester Hub Close Workflow: A five-step gated sequence that enforces: EOC review complete → promotions finalized → payment setup begins → deactivation processed → semester archived. Payment setup is literally blocked until promotions are marked complete — directly preventing the cascading corrections that were the admin's most painful operational problem.

The screens matched the specification, but the data behind them didn't hold up. During a staff walkthrough, an "Active" student had a "Cancelled" subscription. A full-scholarship student showed a $199 payment. A group claimed 5 members but listed 4. The mock data was undermining the demo.

An audit cross-referenced all 33 data files and found five categories of issues:

• 4 students with contradictory states — Active status but Cancelled subscriptions, or active deferments for withdrawn students.
• 54 missing submission records — 14 of 20 students had fewer records than their profile claimed. A student showing "6 submissions" would display 1 in the Submissions tab.
• 4 student groups with wrong member counts
• 4 scholarship-billing mismatches — full scholarships showing full-price payments.
• Dashboard alert tiles that didn't match the underlying data

Each of the 20 mock students was given a coherent story across all screens — a student with failed payments is also behind on submissions, has a filed issue about access, and shows declined charges in billing. Nine cross-reference rules now govern the data so future changes maintain consistency.

The stakeholder delivered a long document in her own words — what she needs on each screen, what she ignores, where the current system breaks down. Alongside that, walking her through the v1 mockup surfaced a second signal: features the v1 spec described accurately but built in a way that didn't fit her mental model.

Every proposed change was catalogued into one of five categories keyed to risk, so the stakeholder review could spend its time on the high-risk ones:

The framework was deliberately conservative. Nine of the biggest proposed changes landed in Categories C and D — changes that would either replace load-bearing v1 mechanisms or expand the information architecture. These couldn't be shipped on stakeholder vibes. They needed a meeting.

A 90-minute session with Lejla, QuranFlow's Project Manager. Every Category C and D item on the table. The goal wasn't to brainstorm — the framework had already done that — it was to resolve each open item with a decision she could stand behind.

Every Category C and D item was resolved. The 11 decisions:

The three load-bearing decisions explain themselves:

• Close Workflow → End Checklist (ADR-001). Lejla: "I'm not too convinced of all these steps that are being proposed." The gated 5-step workflow was designed to prevent specific operational errors (W4: payment setup before promotions finalized). She wanted a flat checklist instead, with backend automation handling the ordering. The decision has a real trade-off — without the gates and without automation, the flat checklist is strictly worse than v1 — and ADR-001 documents that trade-off honestly.
• Assignment Criteria → Hybrid Matrix (ADR-002). The v1 generic rules engine scored 30/35 in the original evaluation for flexibility. But nobody configures assignments as abstract rules — Lejla configures per-TA: "which TAs handle which levels, max capacity for each TA, who takes new vs returning students." The matrix makes the actual configuration surface direct.
• Communication as 9th Domain (ADR-003). v1 had no blast email, no announcement board, no 1:1 messaging, and no communication audit trail. It had Email Management buried under Semester Mgmt and Notifications buried under Admin & System. Pulling all outbound communication into its own domain — with 6 screens, 4 net-new — was the single biggest IA change in v2.

Within 24 hours of the meeting, Framework v2 captured all 11 decisions, five ADRs documented the high-risk ones end-to-end (context, decision, rationale, first- and second-order consequences, what's lost, what's gained, open questions), and the full 12-file v2 admin spec was regenerated from the revised ground truth.

The Apr 15 meeting left ADR-001's core question — "what should the End Checklist actually contain?" — explicitly unresolved. Lejla said: needs to be discussed. The other ADRs had smaller open questions: 13 in total, captured as "defaults I'm making; push back if any feel wrong."

Rather than schedule another meeting immediately, the open questions and proposed defaults were packaged into a Stakeholder Summary and sent to Lejla as a single HTML document. Silence would be acceptance. She replied in writing six days later.

She defined the End Checklist verbatim:

Step 1 — All Submissions Reviewed. Auto-completes when there are no more pending submissions.

Step 2 — Pass/Fail. Every L1–4 student marked pass or fail by their TA or admin. Mastery students excluded — auto-passed at Step 5.

Step 3 — Send Pass/Fail Emails. Pass email, fail-with-opt-in-to-repeat email, or mastery-elective email — whichever applies per student.

Step 4 — Set Up Automatic Payments. Passing L1–4 recitation students get auto-created subscriptions. Mastery students self-enroll.

Step 5 — Semester Close. Fully automatic at midnight EST on the semester end date.

Eleven of the 13 defaults were confirmed as proposed. Two were flipped:

• Announcement Board posters: proposed "admin-only" → actual "admins AND TAs can post." Rationale: TAs manage their own posts.
• Level 0 promote target: spec said Level 1 → actual Level 2. Lejla: "Level 0 is a placeholder for students whose level hasn't been assessed yet, and our default has always been to place them at Level 2. The spec saying Level 1 is an error — please update accordingly." Spec error caught before build.

Her 5-step definition did more than close out ADR-001 — it surfaced new design work that wasn't in the v2 spec yet. Where does the TA actually assign pass/fail? Where does the admin see which students still need payment setup? Which system-seeded email templates power Step 3? These became four design-decision calls made on the spot (documented in the follow-up email as "flag if wrong; silence = acceptance") so the build could start without waiting on a second round-trip.

A 60-minute working session to close out the three topics that had been deferred through both earlier rounds. Three surprises came out of it:

Surprise 1 — v1 had a wrong policy baked in. Both v1 and the draft v2 spec said: "repeat students should be auto-assigned to their previous teacher." Lejla's actual policy, stated plainly in the session: "for repeat students, we will assign them to a different teacher, if at all possible." The rule is rotation, not continuity — so the student sees a fresh perspective on the level they're redoing. ADR-002 was amended the same day; the named rule renamed from "Repeat-Student Auto-Assign" to "Repeat-Student Rotation."

Surprise 2 — "Delete" was the wrong word. The v1 Issue Queue had a Delete action whose semantics were never specified. Lejla's framing: Resolve means "handled, kept in history"; the missing verb is "not a real issue, still kept in history" — Reject. No issue is hard-deleted. Archive is a view over Resolved + Rejected, not a fifth state. Delegation (to CS, IT, or Teaching Staff) is an In Progress sub-state — informational only, admin retains ownership. ADR-006 captures the full state machine.

Surprise 3 — Reporting needed less than feared. The Apr 15 framing treated Reporting as a Category E black box ("needs definition"). The session resolved it with concrete asks: two primary reports (Active Semester Enrollment, Revenue Breakdown), two nice-to-have stubs (Installment→One-Time Conversion, Notification/Email Impact), CSV export only, live dashboards rather than scheduled emails. Enough to build against without waiting for a full reporting working session later.

The lesson worth taking forward: no amount of specification quality catches every stakeholder-side misread. The TA-rotation policy had been frozen into v1 and carried into the v2 spec draft. It was only the working-session conversation that surfaced the inversion. The cost of catching it at the spec stage was a one-line amendment and a mock-data rewrite in one file. The cost of catching it at launch would have been an operational regression affecting every semester close.

v2 is not a replacement for v1 — it's a parallel build. src/pages/ (v1) is frozen; src/pages/v2/ (v2) runs alongside it in the same Vite bundle, mounted under a /v2/* route tree. Both are deployed together at the same URL. Contractors and stakeholders can load / for the v1 reference and /v2/ for the revised design and compare screen-for-screen.

The build ran as 8 named phases in a single long push, with deliberate topology at each stage:

Three build patterns earned their keep under real time pressure:

• Spec-extraction as first deliverable. Every parallel teammate's first commit was a chore: extract spec checklist reading every column, filter, action, and state from their assigned spec section. Loose prompts let teammates skip this. When the Comm teammate hit a rate limit mid-stride, its spec checklist had already landed — the bleed-through edits were coherent enough for the lead to salvage. The pattern turned out to be a rate-limit contingency plan too.
• Pre-flight rebase check. Worktree teammates started from a pinned base; before merge, the lead rebased onto main. This caught stale bases on three separate occasions across Waves 1, 2, and Phase D — load-bearing, not ceremony.
• Post-commit plan sync. A background agent updated IMPLEMENTATION-PLAN.md after every commit. The durable plan document stayed in sync with reality rather than drifting into a historical artifact halfway through.

v2 ships feature-complete against the revised spec. The deferred items in docs/IMPLEMENTATION-PLAN.md are all production-scope (backend End Checklist triggers, real email delivery, Stripe webhooks, TA-facing pre-draft queue) — mockup-appropriate placeholders stand in for each, and every placeholder links back to its spec section.