Admin & Operations

Administrators have a bird's-eye view of the platform via the tile-based admin dashboard.

Core Management Areas

  • Users: Invite new users, suspend accounts, or edit profiles. You can also "Pause" a user (same as the "Taking a Break" feature).
  • Lessons: Oversee the entire lesson catalog, run database migrations, or seed default templates.
  • Emails: Monitor the logs of all sent emails (transactional and marketing).
  • Settings: Configure global settings, point values, and feature flags.
  • Automation: Manage recurring AI lesson jobs and token-based automation access.
  • Cron: Manually trigger system jobs (like "Start Date" notifications) or simulate time for testing.
  • Profile: View your own profile with extra admin controls.

System Jobs (Cron)

LessonHub runs automatic jobs to keep things moving:

  • Hourly: Sends "Start Date" notifications (runs daily at 10:00 UTC on some plans).
  • Daily (09:00 UTC): Sends assignment reminders and weekly summaries.

Testing: You can use the Cron Test page to simulate specific times and ensure emails are firing correctly.

Database & Maintenance

  • Migrations: Always run via the provided npm scripts to ensure safety.
  • Seeding: If default templates or badges are missing, the seed script restores them without deleting existing data.
  • Automation Tokens: After pulling automation changes, run the latest Prisma migration before issuing any tokens or calling the new automation APIs.

Codex Automation For Lesson Creation

LessonHub now supports admin-granted automation tokens so Codex automations can create lessons through server-to-server API calls without using a browser session.

Admin Setup

  1. Open Admin > Automation Tokens.
  2. Choose the teacher account that should own the lessons created by automation.
  3. Create a token and copy it immediately. The full token value is only shown once.
  4. Store the token in /Users/mario/code/LessonHub/lessonhub-app/.env.automation under AUTOMATION_TOKEN. Do not paste it into docs, chats, or shared screenshots.

Local Secret File

Use .env.automation in the project root for Codex automation secrets and defaults:

AUTOMATION_TOKEN=your_real_token_here
DEFAULT_CLASS_ID=your_class_cuid_here
DEFAULT_CLASS_NAME=Fall 2025
  • AUTOMATION_TOKEN is required.
  • DEFAULT_CLASS_ID is recommended if the automation should always target the same class.
  • If DEFAULT_CLASS_ID is omitted, the current terminal test flow calls the remote automation context API and falls back to the teacher's active class named Fall 2025.
  • DEFAULT_CLASS_NAME can be changed if you want a different name-based fallback.

Supported Endpoints

  • Standard lessons: POST /api/automation/lessons
  • Multi-choice lessons: POST /api/automation/lessons/multi-choice

Both endpoints require:

  • Authorization: Bearer <token>
  • Content-Type: application/json
  • a topic field so the automation has a stable subject for the generated lesson

Standard Lesson Example

curl -X POST https://your-domain.com/api/automation/lessons \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Restaurant English",
    "assignmentText": "Answer in complete sentences.",
    "questions": [
      {
        "question": "How would you ask for the bill?",
        "expectedAnswer": "Could I have the bill, please?"
      }
    ],
    "difficulty": 2,
    "assignment": {
      "studentIds": ["student_cuid_here"],
      "classIds": ["class_cuid_here"],
      "startDate": "2026-03-27T13:00:00.000Z",
      "deadline": "2026-03-29T21:00:00.000Z",
      "notificationOption": "immediate",
      "reassignExisting": false
    }
  }'

Multi-Choice Lesson Example

curl -X POST https://your-domain.com/api/automation/lessons/multi-choice \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Travel vocabulary",
    "questions": [
      {
        "question": "Which phrase asks for directions?",
        "options": [
          { "text": "Where is the station?", "isCorrect": true },
          { "text": "I need a taxi.", "isCorrect": false }
        ]
      }
    ],
    "difficulty": 3,
    "assignment": {
      "classIds": ["class_cuid_here"],
      "notificationOption": "on_start_date",
      "reassignExisting": true
    }
  }'

Payload Notes

  • title is optional. If omitted, LessonHub uses topic as the title.
  • difficulty must be an integer from 1 to 5.
  • price is optional and defaults to 0.
  • assignment_notification and scheduled_assignment_date work the same way as the teacher-facing lesson APIs.
  • Standard lessons require assignmentText and at least one question prompt.
  • Multi-choice lessons require at least one question, at least two options per question, and exactly one correct option.
  • The optional assignment block lets automation target specific studentIds, classIds, or both.
  • If assignment is omitted, LessonHub falls back to the lesson-level auto-assignment behavior.
  • assignment.notificationOption supports immediate, on_start_date, or none.
  • assignment.reassignExisting resets existing assignments for the targeted students instead of silently skipping them.
  • assignment.startDate and assignment.deadline apply to every resolved student in that automation call.
  • A practical default is to send assignment.classIds using DEFAULT_CLASS_ID from .env.automation.
  • In the current test script, lessons are assigned to the configured class automatically. If no class id is configured, the script resolves the class through GET /api/automation/context and looks for the teacher's active class named Fall 2025.

Security Rules

  • Tokens are scoped to a specific teacher account.
  • Tokens are stored hashed, can be revoked from the admin panel, and track last use.
  • If a token is leaked, revoke it immediately and issue a new one.
  • Keep automation tokens separate from personal AI keys or .env.local app secrets.

In-App Daily Lesson Automations

LessonHub can now generate daily standard lessons directly inside the app using the configured Gemini API key and the existing Vercel cron flow.

How It Works

  • Create one or more jobs from Admin > Automation.
  • Each job targets one teacher and one active class.
  • The daily cron route processes enabled jobs once per day.
  • Each job stores its own run history and will not create a second lesson for the same day.

What You Can Control

  • Job name
  • Teacher
  • Class
  • Enabled or disabled state
  • Difficulty
  • Price
  • Optional custom prompt to steer Gemini
  • Optional theme pool to control topic rotation

Operations

  • Use Run now from the Automation page to test the jobs immediately.
  • Use Admin > Cron to trigger the daily lesson automation manually with an optional reference date.
  • Daily lesson jobs depend on a configured Gemini API key in the admin AI settings.

Security & Best Practices

  • Secrets: All sensitive keys (database passwords, API keys) are stored in .env.local and never shared.
  • Data: Financial values (like prices) are handled with high precision.
  • Leaderboards: Savings are displayed clearly with color-coding (Green for positive, Red for negative) to avoid confusion.

Support Playbook

Common admin tasks:

  • Hub Guide Access: If a student claims they paid but can't see guides, check their payment status in their Profile.
  • Lyric Errors: If teachers report issues with lyric lessons, it often means a database migration is needed.
  • Timezones: Encourage all users to set their timezone. Incorrect timezones are the #1 cause of "missed" deadlines.