Platform Manual

Routing Structure

Key Conventions

• • All times stored in UTC, displayed in IST (Asia/Kolkata).
• • Razorpay webhooks are the source of truth for subscription state.
• • Server components by default; "use client" only when state/effects needed.
• • All API routes return { data, error } shape.
• • Monetary amounts stored in paise (×100 for Razorpay).
• • getRazorpay() and getResend() are lazy factories — safe to import at build time.
• • Middleware at middleware.ts gates /platform/* routes — checks session cookie.
• • Gamification points are calculated on-write, not in batch.

Access Control Tiers

Login Flow

1. User visits /login and submits email/password or clicks Google.
2. NextAuth issues a JWT session cookie (next-auth.session-token).
3. JWT payload includes: id, email, role, name, image, gamificationLevel.
4. Middleware at middleware.ts reads the cookie — unauthenticated requests redirect to /login.
5. Admin role is checked server-side via session.user.role === "admin".

Session Helper

Use getSession() from lib/session.ts in server components (React-cached, avoids N+1 queries). Use auth() from lib/auth.ts directly in API routes.

Checkout Flow

1. POST /api/subscriptions/create — creates a Razorpay subscription, returns subscription_id.
2. Front-end opens the Razorpay checkout modal with the subscription ID.
3. On payment success, front-end calls POST /api/subscriptions/verify with signature.
4. Razorpay fires webhook to POST /api/webhooks/razorpay — this creates/updates the Subscription record.
5. Webhook also triggers welcome email, in-app notification, and gamification points.

Coupons

Coupons are managed at Admin → Coupons. Supported types: PERCENT and FLAT. Validate via POST /api/coupons/validate at checkout time. The coupon code is stored on the Subscription record for auditing.

Webhook Events Handled

• subscription.activated — mark subscription active, send welcome email
• subscription.charged — renewal confirmed
• subscription.cancelled — mark cancelled
• subscription.halted — mark expired, send reminder
• payment.failed — log failure

Posts

• • Categories: General, Wins, Questions, Resources, Announcements, Events
• • Media: Images, videos, links supported. Uploaded via /api/posts/upload to Vercel Blob.
• • Pinning & hiding: Admin can pin important posts and hide inappropriate ones.
• • Polls: Posts can include a poll (stored as JSON in pollData).
• • Gamification: +5 pts on post creation; +2 pts per like received.

Comments & Likes

• • Threaded: Comments can have a parentCommentId for reply threads.
• • Likes: Works on both posts and comments. A user can only like once per item.
• • Gamification: +3 pts for creating a comment; +1 pt per like received on a comment.

Notifications on Activity

When someone comments on or likes your post, an in-app notification is created. Notification bell in the header shows unread count. Clicking marks them read. The unread-reply badge(orange “Tap to reply”) appears for notifications the user has seen but not yet acted on — tracked in localStorage under notif-actioned.

Content Hierarchy

Course → Module → Lesson

• • Course: Has a cover image, description, access level (free/paid), and sort order.
• • Module: Grouping of lessons within a course. Has a sort order.
• • Lesson: Video URL, Markdown content, action items (JSON array), completion tracking.

Access Gating

• • Lessons with isFree = true are accessible to all signed-in users.
• • The first lesson of the first published course is always free (preview).
• • All other lessons require an active subscription — shown as UpgradeWall if not subscribed.
• • Admin bypasses all gates.

Progress & View Tracking

• • Completion: Marked via POST /api/lessons/[id]/complete. Stored in UserLessonProgress. Awards +5 pts; +50 pts on full course completion.
• • View tracking: LessonViewTracker client component fires POST /api/track/lesson on mount. Inserts into lesson_views table (used in weekly report).
• • Prev / Next lesson navigation is shown at the bottom of each lesson page.

Drip Content

If a course has isDrip = true, lessons are unlocked based on dripDayOffsetrelative to the member's subscription start date. This is enforced in the lesson page access check.

Adding Resources (Admin)

• • Admin sees an “Add Resource” button on the Resources page (top-right).
• • Supports single file, multiple files, external links, and video URLs.
• • Multi-file upload: Multiple files are grouped under a Folder Name. Each file is uploaded individually with ?skipNotify=true, then one summary notification email is sent via POST /api/resources/notify.
• • Single file: Requires Title, Category (folder), Type, and optional description. Sends individual email on upload.

Folder Accordion UI

Resources are grouped by their category field and displayed as collapsible folder cards (ResourceFolderView component). Each folder shows file count and total size. If only one folder exists, it auto-opens. Clicking a file fires a resource view event.

Member Notifications

• • Paid members: Get email with resource title/link to /resources.
• • Free users: Get a teaser email with a link to /subscribe and pricing CTA.

Free Resources (Public)

Separate from the vault — managed via Admin → Free Resources. These are links/resources visible to all signed-in users at /free. Stored in the FreeResource model.

View Tracking

Every resource click fires POST /api/track/resource. Inserts a row into resource_views table. Used in the weekly analytics report to show engagement trends.

Creating & Editing Events

• • Admin creates events via Admin → Events with: title, date/time (IST), duration, category, meeting link, recording URL.
• • Event times are saved in UTC, always displayed in IST (Asia/Kolkata).
• • A double-conversion bug was fixed: the form input is IST → converted once to UTC on save. Never double-convert.
• • Editing: Admin can edit all event fields inline via the event card.

Reminders

• • POST /api/events/[id]/remind sends email reminders to all paid members.
• • Admin always receives a notification copy regardless of event type.

Points Table

Level Thresholds

Weekly Report (Friday 9 AM IST)

Auto-generated email report sent every Friday at 9 AM IST via /api/cron/weekly-report. Can also be triggered manually from admin or via GET request with the cron bearer token.

Metrics tracked (this week vs last week):

Alert thresholds:

• • 🔴 Zero new signups
• • 🔴 Signups dropped ≥ 25% week-over-week
• • 🔴 No new paid conversions (when free users exist)
• • 🔴 Paid conversions dropped ≥ 30%
• • 🟡 Community engagement dropped ≥ 25%
• • 🟡 Lesson completions dropped ≥ 25%
• • 🔴 3+ subscriptions cancelled/expired

View Tracking Tables

Two raw SQL tables (not Prisma-migrated — created via GET /api/admin/run-migrations):

• • lesson_views (id, lesson_id, user_id, viewed_at) — logged every time a lesson page loads
• • resource_views (id, resource_id, user_id, viewed_at) — logged on resource click

Funnel Events

The UserEvent model tracks conversion funnel milestones:signup, subscribe_page_view, checkout_started, subscription_created. Visible in the Admin Analytics dashboard.

Email Types

Admin Newsletter Tool

• • Admin → Email tab: compose newsletter manually or with AI-powered composition (uses Gemini API).
• • Draft workflow: write → preview → approve → send. Drafts stored in SystemSetting table.
• • Broadcasts can be targeted to all members, paid only, or newsletter subscribers.
• • Gmail integration available for OAuth-authenticated sending.

Subscriber Management

Newsletter subscribers (separate from members) are stored in EmailSubscriber. Managed at Admin → Subscribers with bulk import/export, UTM tracking, and unsubscribe handling.

Authentication

Community

Resources

Classroom

Subscriptions & Payments

Events

Messages

Admin Utilities

Deploying to Vercel

1. Ensure all env vars are set in Vercel project settings.
2. Run npm run build locally first to catch TypeScript errors.
3. Deploy: vercel --prod
4. After first deploy (or after adding new models): call GET /api/admin/run-migrations to create raw SQL tables.

Database Migrations

• • Schema changes: edit prisma/schema.prisma, run npm run db:migrate (requires DATABASE_URL).
• • View data: npm run db:studio — opens Prisma Studio GUI.
• • Seed courses: npm run db:seed — loads 8 courses and 70+ lessons.

Post-Deploy Checklist

• □Verify Razorpay webhook URL is set to https://foundersfuelacademy.com/api/webhooks/razorpay
• □Run GET /api/admin/run-migrations to create lesson_views + resource_views tables
• □Send a test email via POST /api/admin/test-email
• □Confirm cron jobs are active in Vercel Dashboard → Settings → Cron Jobs
• □Check admin panel loads at /admin