Running VIVA — the admin operating manual

What admin can and can’t do

The admin role is the highest-trust role on the platform. Admins can create and modify other users (including other admins), edit the course catalog, issue and revoke certificates, change branding, and send messages. Admins cannot change their own role (a self-demotion guard).

Roles at a glance

The admin dashboard

Visit /admin. The page is organised top-to-bottom by frequency of use:

1. Launch readiness — production status, a snapshot of integrations and blockers.
2. User management — create / edit accounts.
3. LMS console — courses, modules, content.
4. Chapter videos — paste YouTube URLs.
5. Certification test editor — design / edit tests.
6. Certificate manager — issue / revoke / view.
7. Catalog history — audit log of every change.
8. Branding studio — colours, copy, footer.

User management

Creating a new account

1. From the admin dashboard, scroll to User management.
2. Click Create user.
3. Enter full name, email, role (admin / operations / trainer), and an initial password (at least 8 chars).
4. Click Save. The account is created immediately. Share the credentials securely with the user — over WhatsApp or a phone call rather than email.

Editing a user

1. Find the row in the users list (filter by role to narrow).
2. Click Edit access on the row.
3. Update name or role. The role select is disabled if you’re editing yourself — admins can’t change their own role.
4. Save.

Removing access

We don’t hard-delete user records (audit trail). Instead, change the user’s role to student with a clearly-bogus password — they retain history but can’t log in. For a former trainer or ops member, this is the right pattern.

The course catalog

The course catalog is the single source of truth for what VIVA offers. Every surface that mentions a course — the homepage, the programmes page, the application form, Razorpay’s description, the certificate page — reads from this catalog. Change it once, every surface updates within 60 seconds.

Where catalog data lives

Catalog data is in apps/api/app/course_catalog.py (server source-of-truth) and mirrored to the frontend ISR fallback at apps/web/lib/courses-data.ts. The admin UI doesn’t yet have an in-product editor for the catalog itself; changes go through engineering for now. You’ll see them in the catalog history once they ship.

Adding a new course

1. Decide the course code (e.g. P·06), name, fee, and cohort dates.
2. Write a 1-paragraph description matching the editorial tone of the existing courses.
3. Hand the spec to engineering. They’ll add it to course_catalog.py, deploy, and the new course appears across all surfaces.
4. Within 60 seconds of deploy, the catalog history shows the new entry.

Chapter videos

For chapters marked as video or guest_speaker, you paste a YouTube URL and the student LMS embeds it.

Recording · upload · paste flow

1. Record the session on VIVA’s YouTube channel as Unlisted (not Private — Unlisted lets us embed; Private blocks embedding).
2. Copy the YouTube URL (any form works: youtu.be/xxx, youtube.com/watch?v=xxx, etc.).
3. Open /admin › Chapter videos.
4. Find the chapter by course code + week number.
5. Paste the URL into the input. Live ID detection confirms it’s valid (a small green tick appears).
6. Click Save. The video is now live in the student LMS within a few seconds.

Certification tests

Each course can have one certification test. Pass score, retake window, and question set are admin-configurable.

Designing a test

1. Admin dashboard › Certification test editor.
2. Pick the course from the dropdown.
3. Set the pass score (default 75%) and the retake window (default 14 days).
4. Click Create test.
5. Add questions one at a time. Two types are supported:
   • True / False — type the correct answer as the literal string true or false.
   • Multiple choice — one option per line. In the correct answer field, type the exact text of the correct option.
6. Save each question. The student LMS shows the test as available once they’re enrolled and the test is unlocked.

Editing after publishing

You can edit existing questions, add new ones, or remove ones that turned out to be unclear. Edits apply to future attempts — existing attempts retain their original score. If you want to invalidate prior scores, reach for the certificate manager (revoke).

Certificate manager

Certificates are normally auto-issued — when a student passes the certification test, a certificate is created within seconds. The certificate manager is for the cases where you need to step in manually.

Manual issue

1. Admin dashboard › Certificate manager.
2. Click Issue manually.
3. Enter the application ID (required), course ID (optional), and a notes field for the audit trail (recommended).
4. Save. The cert appears in the table with a public verification URL.

Revoking a certificate

Use revoke when a certificate was issued in error, or when a student is found to have violated the honour code on the test. Revoke is immediate and public — the verification URL switches to a not valid state the moment you save.

1. Find the cert row in the certificate table.
2. Click Revoke.
3. Enter a clear reason (this is stored on the audit trail — be precise).
4. Confirm. The cert is revoked instantly.

Re-issuing after a correction

If a cert went out with the wrong name or date: revoke the old one, update the application record, then manually issue a new cert. The new cert gets a new URL; share it with the student.

Catalog history

Every change to the course catalog is logged automatically and visible at admin › Catalog history. The table shows:

• When the change happened (timestamp, UTC).
• Which course was affected.
• Which field changed (e.g. fee_inr, coming_soon).
• The before and after values.
• The commit SHA + commit message — links back to GitHub for the underlying code change.

Used for: regulatory disclosures, dispute resolution, and a quick answer to questions like “when did the P·01 fee change?”

Branding studio

The branding studio at admin › Branding lets you adjust:

• Primary & accent colours (used on buttons, headings, accents).
• Brand name (displayed in the navbar & footer).
• Academy name (longer, used in certificates & emails).
• Custom domain (if you ever onboard a white-label tenant).

Changes apply immediately on save. The branding fields are tenant-scoped — for multi-tenant deployments each tenant has its own brand.

Messaging center

The messages page at /messages lets admins (and ops) send broadcast or targeted messages to students. Channels supported: email (via Resend) and WhatsApp (when configured).

Sending a broadcast

1. Open /messages.
2. Click New message.
3. Pick audience: all students, specific cohort, specific batch, or individual student.
4. Pick channel: email, WhatsApp, or both.
5. Type subject + body. Markdown is supported in the body.
6. Preview. Send.

Every dispatch is logged in the message events table — who sent it, who received it, what status (delivered / bounced / failed). Useful for follow-up.

Common workflows

Onboarding a new trainer

1. Create a user account with role trainer.
2. Generate a one-time onboarding link via the trainer-invites section.
3. Share the link with the trainer — they complete their profile (bio, photo, expertise) without you needing to handle each field.
4. Once their profile lands, review & approve it. They’re now visible on the public trainers page.

Opening a coming-soon cohort for enrollment

1. Engineering flips the coming_soon flag on the course in the catalog.
2. The catalog change is detected on the next read — the cohort-announce hook fires automatically.
3. Every reservation-holder (students who paid the ₹5,000 advance) gets a balance-reminder email with a 14-day window.
4. You don’t need to do anything manually — but watch the messaging center to confirm sends went out.

Closing a cohort

1. Wait until every enrolled student has either passed or failed the certification test.
2. Review the certificate manager — confirm every passing student has a cert.
3. Pull the cohort report (placement, attendance, completion stats) from the operations workbench.
4. Archive the cohort batch — sets it inactive but preserves all data.

Safety rails & what NOT to do

• Don’t mark a student as paid by directly flipping payment_stage. The platform’s revenue gate runs off the Razorpay webhook. If you need to record a cash or bank-transfer payment, write the application ID + amount to the operations team — there’s a controlled override path being added.
• Don’t share an admin account. Each admin gets their own credentials. Audit logs only mean something if they identify a person.
• Don’t revoke a certificate without a documented reason. The reason is stored on the cert record forever and is visible to anyone with the verification URL.
• Don’t edit a student’s name without a paper trail. If a student requests a name correction (typo, marriage, legal change), capture the request + supporting document before changing.
• Don’t bulk-message during exam hours. Coordinate with the trainer team so notifications don’t distract students mid-test.