Admin Panel Operation Manual

Deploy TeachCopilot

TeachCopilot ships as a standard Docker image (ghcr.io/greateyin/single-class), so it runs on any container host: a VPS with docker compose, Render, Railway, Google Cloud Run, or Fly.io. This walkthrough uses Fly.io, tested end-to-end from a brand-new account to a running app.

1. Create a Fly.io account

Go to fly.io/app/sign-up and sign up (GitHub OAuth is fastest if you already have a GitHub account).

Right after signing up you'll see a banner asking you to add a payment method — click it and add a card. Once verified, the dashboard unlocks:

2. Install the CLI and create the app

curl -L https://fly.io/install.sh | sh
flyctl auth login
flyctl apps create my-single-class --org personal

3. Provision Postgres

Use Fly Postgres for the simplest setup (same private network as your app), or bring your own external Postgres (Neon, Supabase, RDS) and skip straight to step 5.

flyctl postgres create \
  --name my-single-class-db \
  --org personal \
  --region nrt \
  --vm-size shared-cpu-1x \
  --volume-size 1 \
  --initial-cluster-size 1 \
  --autostart

This prints a connection string — save it, it's shown only once.

4. Authenticate the private image pull

The image is private on GHCR. Generate a classic GitHub token (not fine-grained) with the read:packages scope at github.com/settings/tokens/new, then:

docker login ghcr.io -u <your-github-username>
# paste the token as the password when prompted

5. Set secrets before the first deploy

flyctl postgres attach my-single-class-db --app my-single-class

flyctl secrets set --app my-single-class \
  AUTH_SECRET="$(openssl rand -base64 32)" \
  AUTH_URL="https://my-single-class.fly.dev" \
  NEXT_PUBLIC_BASE_URL="https://my-single-class.fly.dev" \
  ENABLE_MIGRATIONS=true

6. Write fly.toml and deploy

app = "my-single-class"
primary_region = "nrt"

[build]

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 0

[[vm]]
  size = "shared-cpu-1x"
  memory = "512mb"

flyctl deploy --image ghcr.io/greateyin/single-class:latest \
  --app my-single-class \
  -c fly.toml \
  --local-only \
  --now

--local-only pulls the private image through your own authenticated Docker session (step 4) instead of Fly's remote builder, then pushes it into Fly's registry. Use v1.4.2 or later — earlier tags shipped with a broken license public key baked in, so no license key would ever activate. :latest always points to the newest tag, so it's unaffected.

7. First boot

With DATABASE_URL and ENABLE_MIGRATIONS=true already set from step 5, the app runs migrations on first boot and every machine agrees on the same database — visiting your app's URL goes straight to admin account creation:

Sign in with the credentials you just created, and the instance is fully live — confirmed reliable across repeated requests, unlike the unconfigured-secrets path described above. First boot also seeds one example course and one example digital product automatically, so there's real content to click through immediately instead of an empty dashboard (set SEED_DEMO_CONTENT=false before first boot to skip it):

Custom domain

flyctl certs add courses.example.com --app my-single-class

Update AUTH_URL and NEXT_PUBLIC_BASE_URL and redeploy.

Test Access

The screenshots in this revision were captured against the live production instance. If you are following along on your own deployment, sign in with your own admin account. The URLs below are illustrative.

If running locally instead:

pnpm dev
# or
PORT=4000 npx next dev --port 4000

Scope & Coverage

Graphify identifies the admin surface across these major communities:

GitNexus confirmed admin-related files under src/app/admin, covering:

Admin Layout

The admin panel uses a persistent left sidebar and a main work area. The sidebar is the primary navigation for all admin modules.

Sidebar Navigation

1. Dashboard

Path/admin/dashboard

The dashboard is the first admin overview page.

Main Uses

Recommended Operator Flow

1. Sign in as admin.
2. Open /admin/dashboard.
3. Confirm revenue and order totals look reasonable.
4. Use the sidebar or the Workspace shortcuts for deeper management.

2. Users

Path/admin/users

The Users section manages registered accounts.

List Page

User Detail

Path/admin/users/[userId]

Use this page to inspect and manage one account.

Operational Notes

• Do not demote the last known admin unless another admin account exists.
• Disabling/demoting a user blocks admin access but does not delete order records.
• Email identity changes should be handled carefully because orders and ownership records depend on user identity.

3. Courses

Path/admin/courses

Courses are the primary learning product type. A course contains curriculum modules, lessons, landing-page copy, pricing, social proof, reviews, comments, and publication settings.

Course List

Course Editor Tabs

3.1 Intended Learners

Path/admin/courses/[id]/intended-learners

This tab is reserved for defining who the course is for, but is not built yet. It currently shows a "Coming Soon" notice. Use the Landing Page's course description and features list to communicate audience fit in the meantime.

3.2 Curriculum

Path/admin/courses/[id]/curriculum

The curriculum editor manages course structure.

Curriculum Workflow

1. Type a section name into Add New Section and click Add Section.
2. Under each section, type a lecture title into Add a new lecture... and click Add Lecture.
3. Click into a lecture to fill its markdown body, video/embed URL, and attachments.
4. Publish lessons when ready. A course cannot be published while it has zero published lessons.
5. Drag to reorder sections/lessons to match the intended learning path.

3.3 Landing Page

Path/admin/courses/[id]/landing-page

This page controls the content shown on the public course page (/course/[courseId]), which also hosts the inline checkout panel. There is no separate enrollment page; /enroll/[courseId] is only a legacy permanent redirect to it.

Recommended Landing Page Flow

1. Fill Course Title, Subtitle, and a markdown Description (200+ words recommended for SEO).
2. Set Language, Skill Level, Category, and Primary Topic.
3. Add a cover image and OG image.
4. Fill SEO Title/Description/Keywords. Use AI Generate for a first draft, then review.
5. Add 3 to 5 "Everything Included" feature rows with a label and value each.
6. Save, then use Preview to check the public page.

3.4 Pricing

Path/admin/courses/[id]/pricing

Pricing is stored internally in cents but edited as a dollar amount.

Rules

• Paid course prices should be at least 1 cent; use 0 only for intentionally free courses.
• Confirm promo end date and permanent-promo flags before publishing.
• Coupon usage is tracked and should be reviewed if usage limits matter.

3.5 Upsell

Path/admin/courses/[id]/upsell

Configures a one-time offer (OTO) shown immediately after this course is purchased, accepted via one-click charge against the buyer's saved card.

Only published courses/products appear in the Upsell target dropdown. If you see "No published courses available," publish the target first.

3.6 Social Proof, Reviews, Comments

Social Proof/admin/courses/[id]/social-proof

Add named testimonials shown on the landing page via Add Testimonial, then Save Changes.

Reviews/admin/courses/[id]/reviews

Shows average rating, a 1 to 5 star distribution, and the full review list with reply/hide/delete moderation actions.

Comments/admin/courses/[id]/comments

A course-level inbox for lesson Q&A. Filter the thread list by lesson using the left panel; "Include resolved" reveals closed threads.

3.7 Settings

Path/admin/courses/[id]/settings

Controls course-level publication and behavior.

Publish guard: checking Published and saving while no lesson is published yet shows a confirmation dialog:

You can proceed anyway (useful for reserving the public slug ahead of content), but in practice publish at least one lesson first so paying students see something immediately.

4. Digital Products

Path/admin/products

Digital products are downloadable items such as manuals, templates, PDFs, or code bundles.

Product Editor Tabs

4.1 Product Landing Page

Path/admin/products/[id]/landing-page

4.2 Product Files

Path/admin/products/[id]/files

Upload the files delivered to buyers via Add File; drag to reorder if multiple files are attached.

4.3 Product Pricing

Path/admin/products/[id]/pricing

Same pattern as course pricing: dollar-denominated Price (USD), an auto-calculated 3x "Original Price," and Quick Select buttons.

4.4 Product Upsell

Path/admin/products/[id]/upsell

Same OTO pattern as course upsell, but the offer can point at another product or a course. Selecting "A course" reveals an Upsell target dropdown and an optional OTO price in cents override. Again, only published targets are selectable.

4.5 Product Social Proof & Settings

Social Proof/admin/products/[id]/social-proof

Same testimonial editor pattern as course Social Proof.

Settings/admin/products/[id]/settings

5. YouTube Shares

Path/admin/youtube-shares

YouTube Shares create public SEO pages for YouTube videos.

Use Cases

• Turn a YouTube video into an indexed article-style landing page.
• Add summary, links, and calls to action below the embedded video.
• Use a stable slug for sharing.

6. Interactive Modules

Path/admin/interactive-modules

Interactive modules are reusable SVG/GSAP learning widgets that can be embedded inside any lesson or product markdown body.

Embed Syntax

<interactive id="module-slug" mode="explore" />

Click Create Module to build a new one with AI assistance.

7. Orders

Path/admin/orders

Orders represent course enrollments, digital product purchases, free claims, manual orders, and bank-transfer/pending flows.

Order List

Order Detail

Path/admin/orders/[id]

Operational Notes

• Refund and destructive actions should be used only after confirming provider state.
• Pending bank-transfer orders do not represent successful payment until confirmed.
• Enrollment/ownership repair should be used for fulfillment gaps, not as a normal purchase path.

8. Sales

Path/admin/sales

Sales reporting summarizes revenue and sales performance.

9. Profile

Path/admin/profile

The Profile page edits the currently signed-in admin account (name, avatar).

10. Site Editor

Path/admin/site-editor

The Site Editor controls homepage and site-level marketing content with a live split preview: edit on the left, see the rendered homepage on the right. Click Save to publish; Reset discards unsaved edits.

10.1 Courses & Products

This panel has no editable fields. It explains that the homepage grid automatically shows all published courses and digital products, with Manage Courses / Manage Products shortcuts.

10.2 Features

Each feature row has a Title, an Icon picker, and a Description. Reorder or delete rows as needed; section background color is also configurable here.

10.3 Testimonials

Homepage-level testimonials (distinct from per-course/per-product testimonials). Click Add Testimonial to add a quote, name, and optional photo.

10.4 Top Bar

A Show top bar toggle, free-text Notification text, and background/text color pickers for the announcement strip shown above the header.

10.5 Footer

Site-wide brand name (used in page titles, llms.txt, and course pages), copyright text, and footer background/text colors.

10.6 Legal Pages

Upload a favicon and edit the markdown body of the Terms of Service page (and, further down this panel, Privacy Policy and Support content) directly in the admin panel.

Publishing Notes

• Changes appear live in the preview immediately; nothing is public until you click Save.
• Use the desktop/tablet/mobile preview toggle at the top of the editor to sanity-check responsive layout before saving.
• Keep homepage copy in English if the product is configured as English-first.

11. Storage

Path/admin/storage

Storage manages every file uploaded through the application, regardless of which storage provider is active (shown top-right, e.g. "Cloudflare R2").

12. Email Logs

Path/admin/email-logs

Email Logs show transactional email delivery events.

Use Cases

• Confirm purchase confirmation emails were sent.
• Debug password reset, magic-link, or welcome-email delivery.
• Verify Resend/SendGrid configuration changes through recent delivery logs.

13. System Settings

Path/admin/settings

System Settings centralize platform configuration across six tabs: General, Payments, Email, Analytics, Layout, and Integrations.

13.1 General

Shown above. App Name, Brand Display Name, Brand Tagline, Service/Support Email, and support-hours timezone.

13.2 Payments

Per-provider enable toggles and credentials for Stripe, PayPal, and Lemon Squeezy, plus bank-transfer configuration further down the tab. Unlike Email, these toggles are independent — enabling Stripe does not disable PayPal, so a checkout page can legitimately offer more than one payment method at once.

13.2.1 Setting Up Stripe (Test Mode)

1. Sign in to the Stripe Dashboard, switch to Test mode, and go to Developers → API keys. Copy the Publishable key (pk_test_...) and Secret key (sk_test_...).
2. In Admin → Settings → Payments: toggle Enable Stripe on, paste both keys, and save.
3. Required, not optional — create a webhook: Developers → Webhooks → Add destination, listen for checkout.session.completed, point it at the URL shown under Webhook Secret in this tab (https://<your-domain>/api/webhooks/stripe). Copy the signing secret (whsec_...) it gives you back into that field and save again.

13.2.2 Setting Up PayPal (Sandbox)

1. Sign in to the PayPal Developer Dashboard and create (or open) a REST API app under Sandbox.
2. Copy the Client ID and Secret.
3. In Admin → Settings → Payments: toggle Enable PayPal on, paste both values, and save. Webhook ID is optional — leave it blank unless you specifically want PayPal's own delivery logs as a secondary audit trail.

13.2.3 Coupons at Checkout

A coupon is created against exactly one course or one digital product (Pricing tab → Coupon Management/Coupons → enter a code, percentage or fixed amount, optional usage limit and expiry). On the public checkout page, the buyer expands I have a coupon, enters the code, and clicks Apply to preview the discounted total before paying — the discount is calculated the same way regardless of which payment provider is used.

Verified end-to-end (2026-08-22): tested all four combinations of course/digital-product × with/without coupon through Stripe test mode, each as a genuinely signed-out guest checkout. Every purchase correctly: charged the discounted amount when a coupon was applied, appeared in Admin → Orders as Completed, auto-created a new student account with the exact purchase amount as Total Spend, and granted real course enrollment / product ownership (confirmed via each account's own "Enrolled Courses" / "Digital Products" panel, not just the order list).

PayPal verified end-to-end (2026-08-22): tested a course purchase with no coupon and a digital-product purchase with a coupon applied, both through PayPal Sandbox as a genuinely signed-out guest checkout with a real Sandbox test buyer account. Note that PayPal's own checkout popup requires a real user click to open (browsers block script-triggered clicks on it as a popup) and, after approval, a second explicit confirmation on PayPal's own review page — logging in alone does not complete the purchase. Both test purchases correctly charged the discounted amount when the coupon was applied, appeared in Admin → Orders as Completed, and granted real access: course enrollment and digital-product ownership were both confirmed on the same buyer account's "Enrolled Courses" / "Digital Products" panel, and the order-confirmation email was confirmed sent in Admin → Email Logs.

13.2.4 Refunds

Open any Completed order (Admin → Orders → an order row) and scroll to the red Danger Zone card, which only appears while the order is Completed. Refund Order asks for a single confirmation, then issues a full refund — there is no partial-amount or reason field. Once refunded, the button disappears, so the same order can't be refunded twice.

1. Open the order and confirm it's still Completed, then click Refund Order in the Danger Zone card.

2. Confirm the "Refund this order?" dialog — this is the only chance to back out, since the action is irreversible.

3. The button briefly shows Processing Refund... while the server calls the real payment provider's refund API, then a toast confirms success and the order's Status flips to Refunded.

Every row was confirmed as a genuine provider-side refund by querying Stripe's and PayPal's own REST APIs directly after clicking Refund Order in the admin UI — not just trusting the local status flip. Every buyer's account was then checked individually: Total Spend dropped by exactly the refunded amount, and the corresponding "Enrolled Courses" / "Digital Products" panel entry was gone, confirming real access revocation rather than a cosmetic status change.

13.3 Email

Three providers can be configured simultaneously — Resend, SendGrid, and SMTP — each keeps its own credentials, and the Active Email Provider dropdown at the top picks which one actually sends. Switching providers later is instant: no redeploy, just re-save with a different selection. Sender Name applies across all three. Whichever provider is currently active shows an Active badge on its card, as shown above.

13.3.1 Setting Up Resend

1. Sign in at resend.com/api-keys and click Create API key. "Full access" is fine for a single instance; name it something you'll recognize later (e.g. the app's domain).
2. Pick a From Email domain. Either use Resend's shared sandbox address (onboarding@resend.dev — works immediately, but only reliably delivers to your own account's verified email) or, for real customer-facing sending, verify your own domain first under Domains (add the DNS records Resend gives you, wait for the "Verified" badge).
3. Back in Admin → Settings → Email: set Active Email Provider to Resend, fill in Sender Name, paste the re_... key into API Key, and set From Email to an address at your verified domain (or the sandbox address).
4. Click Save Changes.
5. Optional — delivery tracking: create a webhook in Resend Dashboard → Webhooks pointing to https://<your-domain>/api/webhooks/resend, then paste its signing secret (whsec_...) into Webhook Signing Secret. Without this, emails still send — Email Logs just won't show delivered/bounced status updates after the fact.

13.3.2 Testing the Configuration

Every provider card ends with a Send Test Email field. Enter any address, click send, and check three places to confirm it actually worked end-to-end rather than just being accepted by the form:

1. The in-app toast confirms the request was submitted ("Test email sent") — this only means the API call succeeded, not that the message was delivered.
2. Admin → Email Logs records the attempt with recipient, subject, provider, and status (sent means Resend/SendGrid/SMTP accepted it).
3. The provider's own dashboard is the actual source of truth for delivery — e.g. Resend Dashboard → Emails shows each message's real status (Delivered, Bounced, etc.), which is the only way to catch a misconfigured From-domain that the app-side "sent" status won't reveal.

Verified working end-to-end on 2026-08-21: Resend configured with a verified courses.most.tw sender, test email sent to an external Gmail address, confirmed Delivered in both Email Logs and the Resend dashboard.

13.4 Analytics

Third-party tracking IDs: Google Analytics (GA4), Facebook Pixel ID plus Meta CAPI Access Token and Meta Test Event Code, and Microsoft Clarity ID.

13.5 Layout

Edits the same homepage copy fields also reachable from Site Editor → Hero/Top Bar/Footer (Top Bar Text, Hero Headline, Hero Subheadline, Hero CTA Text/Link, Footer Branding). The two surfaces are kept in sync.

13.6 Integrations

Google OAuth (Client ID/Secret, redirect URI for "Sign in with Google"), plus file storage provider and AI provider configuration further down the tab.

14. License Settings

Path/admin/settings/license

License settings show product license state and license-related actions.

License Status Reference

Freemium Content Limits

When the license status is inactive, grace_expired, disabled, or refunded:

• Courses list (/admin/courses): shows at most 1 course. A yellow banner appears showing how many courses are hidden.
• Curriculum editor (/admin/courses/[id]/curriculum): shows at most 1 section. The Add New Section form is disabled.
• Digital products list (/admin/products): shows at most 1 product. The Create Product form is disabled.

These restrictions are UI-layer only. All content remains in the database. Activating a valid license key immediately removes all restrictions; no migration needed.

14.1 Activating a License Key

1. Go to Admin → Settings → License (/admin/settings/license)
2. Paste the SC2-... key into the License Key field
3. Click Activate

The key is validated offline. No internet connection is required during activation.

14.2 Purchasing and Activating a Lemon Squeezy License

If you bought Teach Copilot through a Lemon Squeezy checkout instead of receiving a hand-issued SC2-... key, the key looks like a UUID (e.g. 41A637CD-4320-4216-B274-9045A444F7E5) and validates directly against Lemon Squeezy's own servers — no extra setup on your side.

1. After checkout, open the confirmation email or Lemon Squeezy's My Orders page — your license key is listed under the order.

2. Go to Admin → Settings → License (/admin/settings/license) and click Activate Key.

3. Paste the full key (with dashes) into the License Key field and click Apply. This step requires an internet connection — the key is checked against Lemon Squeezy's servers, not verified offline like SC2 keys.

15. MCP Keys

Path/admin/settings/mcp

Issue and revoke API keys for AI clients (Claude Desktop, Cursor, and any other MCP-compatible client) to connect to this instance's MCP server.

The server speaks JSON-RPC 2.0 over the Streamable HTTP transport at a single flat URL. Every request must include Authorization: Bearer <key>; requests without a valid, active key are rejected. Each key only authorizes the tool categories checked at creation (or later via that key's row). A read-only key cannot call write or destructive tools even if the client requests them.

16. Recommended Admin QA Checklist

Use this checklist after major deployments.

17. Screenshot Inventory

Screenshots in this manual are sourced from a full tour of a live production deployment's /admin, numbered in capture order and stored alongside this page under assets/images/.