# AllGifted Math — Admin Guide A plain-language manual for school administrators using the AllGifted Math admin panel. No engineering background required. --- ## 1. What the admin panel is for You'll use the admin panel to: - **Approve questions** before students see them (QA review) - **Manage student accounts** — roles, lives, subscription status - **Edit lookup tables** — difficulties, fields, levels, statuses, test types - **Edit site configuration** — site name, branding colors, mastery thresholds, batch sizes - **Spot problems early** — the dashboard shows the QA queue, unresolved student reports, and recent activity The panel lives at **https://mathapi.allgifted.com/cp** (production) or `http://127.0.0.1:8765/cp` (local dev). --- ## 2. Logging in The admin login is **OTP-only** — there is no password. You sign in by receiving a 6-digit code at your email or phone, then entering it. **Steps:** 1. Open `/cp` in your browser. You'll be redirected to the login page automatically. 2. Enter your email address (or phone number in international format, e.g. `+6591234567`). 3. Click **Send Verification Code**. A 6-digit code lands in your inbox within seconds. 4. Type the code. If you wait too long, the code expires after 5 minutes — just click "Send" again to get a new one. **Once verified, you'll land at the dashboard at `/cp`.** Your session lasts as long as your browser keeps the cookie (typically until you close the browser). > **If you don't see the email**: check spam. The from address is `ace.allgifted@gmail.com`. If still nothing, ask your developer to verify SMTP credentials. --- ## 3. Dashboard The landing page (`/cp`) gives you a one-glance overview: **Stat cards (top row):** - **QA queue** — questions waiting to be reviewed (`unreviewed + flagged + needs_revision`). Color shifts to warning when there's backlog. - **Open reports** — students have flagged questions to you for review. - **Active users (24h)** — heartbeat metric for whether the system is being used. - **Tests completed today** — daily activity signal. **Tables (below):** - **Latest 10 question reports** — what students have flagged, who reported, when. - **Latest 10 flagged / needs revision questions** — what's in your review queue right now. Click any stat card or table row to drill in. --- ## 4. QA workflow The QA section is where you review questions before they reach students. It's the most important admin task in the system. ### 4.1 The queue (`/cp/qa/queue`) Four **clickable stat cards** at the top — each one is a queue: - **Pending review** (yellow) — never been looked at - **Flagged issues** (red) — someone reviewed and found a problem - **Needs revision** (blue) — a writer needs to rework - **Approved today** (green) — already published today Click a card to filter the table to only that queue. The card you clicked gets a thick colored border and a "Showing this queue below" hint. To clear the filter, click **Clear filter** above the table. Each row in the table has a **Review** button — click it to open the question in the sequential reviewer. **Bulk operations** (select multiple rows via checkboxes): - **Approve & publish** — runs the full workflow on each (skips any with open issues) - **Flag & demote** — prompts for issue type + description, creates an issue on each, demotes them to draft ### 4.2 Sequential review (`/cp/qa/review`) This is the core QA workflow. It loads ONE question at a time with full context, you act on it, and it auto-advances to the next question in the same queue without you having to navigate back. **What you see:** - **Question body** — text and image (if any) - **Options** — for MCQ, the correct answer is highlighted in lime green - **Explanation** — the answer rationale shown to students after they answer - **QA issues** — any previously raised concerns, with a one-click "Resolve" button each - **Hints + Solutions** — the help content students can request - **QA notes** — the running log of reviewer comments **Header buttons (top right):** | Button | What it does | |---|---| | **Approve & publish** | Sets the question to `approved`, publishes it (makes it visible to students), auto-advances to the next question. Blocked if there are any **open** QA issues. | | **Flag & demote** | Opens a form asking for an issue type + description (min 10 chars). On submit, the question becomes `flagged`, creates an issue record, demotes the question to draft (hidden from students), advances. | | **Mark needs revision** | Optional reviewer note. Sets the question to `needs_revision`, demotes to draft, advances. | | **Edit question** | Opens the full edit form for the question in a new tab. Edit content, click Save — your QA review stays on the current question so you can continue. | | **Skip** | Move to next question without taking any action. Useful when you want to come back to this one later. | | **Previous** | Goes back to a question YOU reviewed previously (only visible if you have one). | After any Approve / Flag / Mark needs revision, the page **automatically loads the next question in the same queue** — there's no need to navigate back to the list. **When the queue is empty**: you get a green "No more questions in ''" notification and bounce back to the queue view. ### 4.3 QA workflow rules (the non-obvious ones) - **Open issue blocks approval**: if a question has any QA issues with status='open', you cannot approve it until the issues are resolved (use the Resolve button on each). - **No self-approval**: if you were the last person to edit a question's QA fields, another reviewer must approve it. Admins can override. - **Approving publishes**: when you approve, the question's `status_id` becomes 3 (Public) and `published_at` is stamped. The Flutter app starts serving it to students immediately. - **Flagging un-publishes**: flagging sets `status_id` to 4 (Draft) and clears `published_at`. The question stops appearing to students until re-approved. --- ## 5. Managing users (`/cp/users`) Slim table showing the columns that matter day-to-day: - **ID, First name, Email** — search by any of these - **Role** — badge showing the role name (System Admin, QA Reviewer, Student, etc.) - **Access type** — `free` / `premium` / `trial` / `suspended` — color-coded - **Maxile** — current maxile level (decimal) - **Lives** — current lives count - **Last test date** — when they last took a test **Filters** (left side): - Role - Access type - **Inactive 30+ days** — students who haven't tested in over a month - **Out of lives** — students at 0 lives (might be churn-risk) **Editing a user** opens a sectioned form: - **Identity** — names, email, contact, date of birth - **Role & access** — role, access type, admin flag, status - **Progress** — maxile, kudos, lives, diagnostics taken - **Subscription** — Stripe IDs, plan, dates > **Password and OTP fields are intentionally absent.** This is by design — admin login is OTP-only, and exposing those would be a security hole. To reset a user's auth, they re-request an OTP themselves. --- ## 6. Editing questions (`/cp/questions`) Same layout as the QA queue but unscoped — every question, every status. **Form sections:** - **Question** — skill, difficulty, type (MCQ/FIB), status, body text, explanation, image upload - **Answers** — answer slots (use index 0–3 for MCQ correct answer; for FIB, all slots are accepted answers) - **QA** — qa_status + QA notes - **Misc** — is_diagnostic flag, calculator-allowed flag, source **Bulk QA actions** are also here — same Approve / Flag / Needs revision actions as the QA queue, useful for catch-up after a batch import. **Filters**: qa_status, type (MCQ/FIB), skill. --- ## 7. Lookup tables (lower-priority) These don't need daily attention but are editable when you onboard new content: - **Difficulties** (`/cp/difficulties`) — the difficulty tiers (1, 2, 3, …). The number of tiers drives the skill mastery rule (must pass the top tier to fully master a skill). - **Fields** (`/cp/fields`) — top-level subject areas (e.g. Algebra, Geometry). Questions roll up to tracks, tracks roll up to fields. - **Levels** (`/cp/levels`) — grade-band maxile ranges (start–end). Used by the cascade to compute skill/track maxile. - **Statuses** (`/cp/statuses`) — visibility states. **Important IDs**: 3 = Public (visible to students), 4 = Draft (hidden). Don't reorder. - **Test types** (`/cp/test-types`) — kiasu / track-practice / diagnostic. Don't add new ones without engineering involvement. --- ## 8. Site configuration (`/cp/configuration-page`) One singleton page that controls system-wide settings. Save changes via the **Save changes** button at the bottom; a green toast confirms. **Sections:** - **Mastery thresholds** (three numbers — change cautiously, these affect every student's progression): - *Consecutive corrects to upgrade tier* — default 3. How many in a row to bump a skill's difficulty. - *Consecutive wrongs to downgrade tier* — default 2. - *Maxile recompute window* — default 5. How many recent attempts the adaptive engine looks back at. - **Test batch sizes**: - *Questions per test* — default 10. - *Field-round batch size* — default 5. Used by diagnostic and kiasu mode. - **Site identity** — site name, short name, URL, contact email. - **Maintenance** — toggle to show a maintenance banner site-wide, with a custom message. > **Mail settings are not exposed here.** SMTP credentials live in the server's `.env` file — your developer handles those. --- ## 9. Branding colors Currently set in the database to match the AllGifted brand palette: - **Crimson #960000** — primary action color (buttons, accents, headings) - **Gold #BF9237** — secondary accents, warnings - **Lime #88C808** — success states - **Blue #4A6488** — informational states - **Cream #FDFAF8** — backgrounds, soft surfaces - **Dark #1A0505** — body text These colors flow through to the legacy admin via CSS variables. To change brand palette across all admin surfaces, edit the `configs` row (the engineer can do this via a migration so it persists across deploys). --- ## 10. Common tasks — quick reference | I want to… | Go to | |---|---| | Review questions before publishing | `/cp/qa/queue` → click "Pending review" card → Review each | | Approve a batch of clearly-good questions | `/cp/questions` → filter by `qa_status=unreviewed` → select rows → Bulk action → Approve & publish | | Find a student by email | `/cp/users` → search box (top of table) | | Give a student more lives | `/cp/users` → edit the student → Progress section → set Lives → Save | | Suspend a student | `/cp/users` → edit → Role & access → set status='suspended' → Save | | Change the consecutive-corrects threshold | `/cp/configuration-page` → Mastery thresholds → save | | See who reported a question | Dashboard → "Latest question reports" table | | Edit a question's text | `/cp/questions/{id}/edit` or QA Review → Edit question | --- ## 11. Troubleshooting | Symptom | Likely cause / fix | |---|---| | "Please wait a moment before requesting another code" | 30-second cooldown after requesting an OTP. Just wait, then click Send again. | | OTP email never arrives | Check spam. If still nothing, ask dev to verify SMTP credentials (Gmail app password rotation, etc.). | | /cp says "Forbidden" after login | Your account's `role_id` isn't in the admin allowlist `[1, 9, 10, 11]`. Ask another admin to grant the right role via the User edit page. | | Approve button says "blocked: N open issues" | Open the question (or use QA Review) → find the issues panel → click Resolve on each → then approve. | | Edit form shows fewer fields than expected | Slim by design. If you need access to a hidden field (e.g. partner_id), ask engineering to either expose it in the form or do the change via the legacy admin at `/admin`. | | Page renders but breaks visually | Hard-refresh (Ctrl+F5 / Cmd+Shift+R). Browsers cache the admin CSS aggressively. | --- ## 12. Who can do what — role guide | Role ID | Role name | What they can do | |---|---|---| | 1 | System Admin | Everything | | 9 | Administrator | Everything except destructive infra ops | | 10 | QA Lead | All QA actions + read users + read content | | 11 | QA Reviewer | QA actions only — approve / flag / mark needs revision | | 6 | Student | (no admin access) | > The `is_admin` flag overrides role-based gating for power-users who shouldn't fit neatly into a category. --- ## 13. Need help? Issues, feature requests, and bug reports go to your engineering contact. When you report a bug, include: - What URL you were on - What you clicked - What you expected - What happened instead - A screenshot if visual If the dashboard shows red error counters or `/api/health` returns anything other than "ok", flag it to engineering immediately.