Skip to content

jedafe/japa / .claude/skills/jc-academy-develop

jc-academy-develop

Verified

Use when building new pages or components for the JapaConnect Academy app (apps/academy, port 3003, SSR, academy.japa.to). Covers the unified app shell adapted for Academy (ADR-060), the lesson-player reading exception, the SSR/CSR progress boundary, TrackCard, LayerChart 2.0.1 progress analytics, and the API-Readiness Gate.

JapaConnect Academy — Development Skill

Course/track platform at academy.japa.to. SSR (adapter-node + Bun). API base /api/v1/academy/*. Layout is the unified app shell (ADR-058) adapted for Academy (ADR-060) — build inside it; the lesson player is the one exception.

⛔ API-READINESS GATE

Same as jc-main-develop: list endpoints → verify (catalog or probe) → any missing: STOP + ⚠️ MISSING BACKEND API ROUTES alert. Never mock. Known routes: GET /academy/catalog (marketplace catalog, filters on is_published_to_academy), GET /academy/catalog/options, GET /academy/tracks, GET /academy/tracks/:slug, POST /academy/tracks/:id/enroll, GET /me/enrollments, GET /academy/lessons/:id, POST /academy/lessons/:id/progress, POST /academy/lessons/:id/complete, GET /academy/quizzes/:id + POST /academy/quizzes/:id/submit, GET /me/certificates — verify each before use. Japa Academy (ADR-063) routes: POST /academy/instructor/apply (creator application), GET /academy/instructor/me (own instructor status), GET /academy/my/tracks (instructor course list), POST /academy/my/tracks/:id/submit (submit course to marketplace), GET /academy/my/payouts (instructor payout history), GET /academy/my/earnings (earnings + revenue series) — verify each before use.

Japa Academy Marketplace (ADR-063 — unified shell)

Japa Academy is the Academy platform presented as a worldwide creator marketplace under its own brand. Since the ADR-063 consolidation there is a single Academy shell — the former Learn/University dual-shell is gone. The canonical host is academy.japa.to (or a custom domain from the academy.subdomain / academy.custom_domain system_settings, routed by the edge proxy). Not open sourced (ADR-063 §1).

  • Marketplace catalog: GET /academy/tracks returns only is_published_to_academy = true courses. TrackCard adds a price badge (price_kobo → formatted) and instructor name. Free and Pro-included courses show "Free" / "Pro".
  • Creator flow: POST /academy/instructor/apply → academy_instructor_profiles.status = 'pending'. Admin approves → academy:notify_instructor_approved. Approved instructor creates a track → POST /academy/my/tracks/:id/submit → admin approves course → academy:notify_course_approved → is_published_to_academy = true.
  • Instructor dashboard: /dashboard/instructor — course list with enrollment counts (total_enrolled), revenue overview from GET /academy/my/payouts + GET /academy/my/earnings, pending/approved course status. LayerChart for revenue over time.
  • Pro dual-access: Pro subscribers enroll in any academy course for free. The UI shows "Included with Pro" instead of a price for Pro users. Creators are still compensated (Pro stream rate, ADR-063 §7) — this is backend, not visible in the UI.
  • Course reviews: reuse the polymorphic reviews table (entity_type = 'academy_track'). Star ratings and counts from review_aggregates. No course-specific review UI — use the same review component as Section 29.
  • SSR/CSR boundary unchanged: marketplace catalog is public (SSR); instructor dashboard and payout data are CSR (session-guarded).

⚠️ SSR/CSR BOUNDARY — Academy's Critical Rule

User-specific data is NEVER server-rendered. Progress, enrollment status, completed lessons, quiz scores → CSR only, guarded by session:

// +page.server.ts — public content ONLY (track, curriculum, lesson HTML)
// +page.svelte — user data:
$effect(async () => {
  if (!data.session) return;
  const r = await fetch(`/api/v1/me/enrollments`);
  if (r.ok) enrollments = (await r.json()).data;
});

A +page.server.ts touching /me/enrollments or /academy/lessons/:id/progress is a critical defect (leaks one user's progress into cached SSR responses).

The Shell (ADR-058 primitives, ADR-060 drift)

Adopt AppShell (collapsible LeftNav + center + RightSidebar), ui.nav_collapsed server-persistence (never localStorage), sticky right-sidebar search+avatar, dark-mode tokens, mobile single-column + bottom bar. Nav items from GET /api/v1/menus/academy_nav (ADR-054).

  • Left nav (learning-oriented): Explore (catalog) · My Learning · Paths · Certificates · Bookmarks.
  • Center: catalog grid / track detail / lesson player.
  • Right sidebar: continue-learning card, streak + progress ring, up-next lesson.
  • TrackCard is ONE variant-driven card (Ghost-style: thumbnail, title, LevelBadge, duration, instructor, rating, enrolled count, enroll/continue/locked). Never fork per level/type.

Lesson Player — Academy's Reading Exception (ADR-060, dev.to-single analog)

Route (app)/tracks/[slug]/[module]/[lesson] (or /academy/lessons/:id). Left nav auto-collapses to 72px. Three zones:

  • CurriculumRail — module→lesson tree in the content's LEFT margin: current (▶), completed (✓), locked (🔒), not-started (○). Sticky/scrollable. Belongs to the content — visually distinct from the collapsed nav, NOT a second nav.
  • Center — lesson by lesson_type: article (SSR TipTap .prose + .prose-table-wrapper), video (browser-guarded init, progress_secs tracking), quiz (quiz engine), checklist (TaskList). Mark complete → POST /academy/lessons/:id/complete (optimistic Set, marking guard, rollback, auto-next).
  • Right — lesson meta: track progress ring, Next lesson →, notes.
  • No ads. Access verified server-side (403 if not enrolled and not is_preview → redirect to enroll).

Track Detail (widened overview)

/academy/tracks/[slug]: SSR hero + stats · <Tabs.Root> Overview | Curriculum | Reviews · <Accordion.Root type="multiple"> curriculum · instructor card · enroll CTA · Course JSON-LD.

LayerChart — Learner Analytics (ADR-059)

Pinned layerchart@2.0.1. "My Learning" dashboard: progress over time (LineChart), weekly activity (BarChart), completion/time-spent, streak sparklines. High-level compound charts preferred:

<script lang="ts">import { LineChart } from 'layerchart'; let { data } = $props();</script>
<div class="h-64 w-full"><LineChart {data} x="date" y="pct"
  props={{ spline: { class: 'stroke-[var(--chart-1)]' } }} tooltip /></div>

Rules: colors via var(--chart-*)/var(--color-*) only (dark-mode safe) · fixed-height containers · data from /api/v1/me/* + /academy/* (verify via Gate!) · per-chart skeleton · dates → Date.

Difficulty & Progress Tokens (CSS custom properties, dark-mode safe — never hardcode hex)

--level-beginner (green) · --level-intermediate (amber) · --level-advanced (red) · --color-progress · --color-locked. Define once in the theme; reference as variables.

Stack

Identical base to jc-main-develop: Svelte 5 Runes, Bits UI dot-notation, Tailwind v4, LayerChart 2.0.1, Lucide, TypeScript, $t() i18n (en+fr), Rule 16, no AI attribution. Canonical URLs on academy.japa.to.

Deliverables Per Task

  1. Gate output · 2. surface built INSIDE AppShell (or the lesson-player exception, explicitly) · 3. +page.server.ts (public content only — no user progress) · 4. +page.svelte (SSR content + CSR progress, skeletons) · 5. components · 6. JSON-LD · 7. types V2 academy app: No new pages in v2. Japa Academy (ADR-063) is already implemented. The academy app may receive minor amendments if Japa Academy course visibility is affected by v2 persona authorship or the AI Content Studio publishing courses. Per ADR-060, v2 community features (§§79–89), functional tools (§§90–101), and mentorship (§102) are not part of the academy platform — they live in the Main app (community) and Tools app (functional tools). However, academy content may be cross-referenced from these features (e.g. a functional tool may link to a relevant academy track). Total platform route count is now ~819 (~475 v1 + ~344 v2); 18 Golden Rules (R18: always use bun).

V2 Feature Areas (Implement Only After Corresponding Backend Phase Is Complete)

FeatureBackend phaseKey sectionsGates
JapaBot (RAG-grounded)Phase 41§69/ai/chat amended
AI Content Studio (admin)Phase 42§75studio.* RBAC
Participation queue (admin)Phase 42§76participation.review RBAC
Visa ChecklistPhase 43§70checklist.use RBAC
Readiness AssessmentPhase 43§71assessment.take RBAC
Cost of Living CalculatorPhase 43§72col_calculator.use RBAC
Scholarship FinderPhase 43§73scholarship.browse RBAC
Remittance Rate TrackerPhase 44§74remittance.view RBAC
Referral systemPhase 45§60referral.use RBAC
Self-serve adsPhase 45§61ads.self_serve.create RBAC
NewsletterPhase 45§62newsletter.subscribe RBAC
Jobs boardPhase 45§63jobs.browse RBAC
GamificationPhase 45§64gamification.view RBAC
Content importPhase 46§65import.use RBAC
Advanced analyticsPhase 46§66analytics.advanced RBAC
Travel searchPhase 46§67travel.search RBAC

API-Readiness Gate applies to all v2 features. Verify against api-routes-catalog.md — all v2 routes are marked as "V2 planned" in the catalog. Once the corresponding backend phase lands, the planned routes become available.

Removed surface: apps/tools was consolidated into apps/main (/tools/{tool}) — ADR-086 superseded. tools.japa.to and per-tool subdomains 301 to japa.to/tools/{tool}; the jc-tools-* skills were deleted.

deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall