jc-main-refactor
Use when updating, modernizing, or refactoring existing JapaConnect Main App code (apps/main). Migrates Svelte 4 to Svelte 5 Runes, adopts Bits UI primitives, migrates legacy layouts to the unified ap
SKILL.md.claude/skills/jc-main-refactor/SKILL.md
GitHubJapaConnect Main App — Updating & Refactoring Skill
Apply conventions from jc-main-develop. Do not change behavior — modernize implementation only. One-line comment per change.
0. API-Readiness Gate
If a refactor requires an endpoint that doesn't exist (e.g. replacing hardcoded data with an API call), verify the route first. Missing → output the ⚠️ alert and pause.
1. Svelte 4 → 5 Migration
export let → $props() · $: → $derived() · reactive side-effect blocks → $effect() · createEventDispatcher → callback props · writable stores for local UI state → $state() · on:event → onevent
2. Bits UI Adoption
| Manual pattern | Replace with |
|---|---|
Custom dropdown <ul> toggle |
<DropdownMenu.Root> |
| Custom modal + focus trap | <Dialog.Root> |
Raw <select> |
<Select.Root> / searchable <Combobox.Root> |
| CSS hover tooltip | <Tooltip.Root> |
| Manual accordion / tabs / popover | <Accordion.Root> / <Tabs.Root> / <Popover.Root> |
3. Chart Migration → LayerChart 2.0.1
Any chart built with Chart.js, D3 direct DOM, canvas, inline SVG math, or any other library must be rewritten in LayerChart (pinned layerchart@2.0.1, prefer high-level compound charts):
<!-- BEFORE: Chart.js canvas, manual lifecycle, breaks SSR -->
<canvas bind:this={el}></canvas>
<!-- AFTER: LayerChart v2 compound chart, declarative, SSR-safe -->
<div class="h-64 w-full">
<AreaChart {data} x="date" y="count"
props={{ area: { class: 'fill-[var(--chart-1)]/20 stroke-[var(--chart-1)]' } }} tooltip />
</div>
Use AreaChart/LineChart/BarChart for the mapped dashboard widgets (ADR-059); drop to the low-level <Chart><Svg>…</Svg></Chart> only when a compound chart can't express it. Convert API date strings to Date objects · colors via var(--chart-*)/var(--color-*) only · add skeleton state · pin layerchart@2.0.1 and remove the old chart library from package.json if unused.
3b. Legacy Layout → Unified App Shell (ADR-058)
Migrate pre-shell layouts to the single three-column shell:
- Replace any top-nav-bar layout / bespoke per-page layout with
AppShell(LeftNav+ center +RightSidebar) — except the three exceptions (blog/CPT single,/create, guest homepage). - Collapse a per-content-type
FeedCard(separate components or big{#if content_type}layout branches) into one variant-drivenFeedCardwith a content-type pill + additive props. - Move nav-collapse state from
localStoragetoui.nav_collapsed(PATCH /api/v1/me/account); move the account dropdown to the right-sidebar avatar; keep the Space switcher in the left nav. - Blog/CPT single: make the reaction rail borderless/transparent (
ReactionRail); replace the search/avatar bar withCreatorCard. /create: convert the settings drawer into the tabbed[ Guide | Settings/SEO ]panel with the dynamic field-focus Guide.- Guest
/: render the Page Builder landing (fallback/explore); keep authenticated/on the Primary timeline.
4. Rule 16 — Hardcoded Data Removal
Replace static arrays (nav, countries, tags, groups, post types, chart datasets) with API fetches. Verify the endpoint exists first (Gate 0).
5b. Profile Learning Hub & Cross-App (ADR-060)
- Replace hardcoded certificate/enrollment/knowledge-base lists with
GET /api/v1/me/certificates,GET /api/v1/me/enrollments, and the bookmark routes (no new backend needed). - Extract any Learn/Docs surface re-implemented in this app (lesson player, curriculum rail, docs nav tree) — replace with an absolute deep link to
academy.japa.to/docs.japa.to; those apps own those surfaces. - Consolidate scattered learning links into the dashboard hub tabs:
/dashboard/learning,/dashboard/certificates,/dashboard/knowledge-base. - Point certificate cards at the public shareable page
/certificates/:id; add earned-certificate badges to the public profile.
5c. Geo-Aware Personalization (ADR-064) & University Discovery (Section 39)
- Hardcoded geo → VisitorContext: any hardcoded country/region list or
?geo=default → consumeGET /api/v1/geo/meforContentCountry. The feed header gets an inline "Showing: [Country] · Change" control wired toPATCH /api/v1/me/profile(content_country_preference). - Client-side geo flicker → SSR: if the guest homepage loads global content then swaps to geo client-side, move the geo-weighted fetch into
+page.server.tsso it's in the initial HTML. - Hard geo filter → re-weight: if
?geo=is used to exclude non-local content, change to a boost/optional-filter (ADR-064: re-weight, never hide). - University pages → shell + API: any standalone-layout university page → migrate into
AppShell; any hardcoded university data →GET /api/v1/universities/GET /api/v1/universities/:slug. Add JSON-LDEducationalOrganization+AggregateRating. - University discovery: add
/universities(grid, filters from API, geo-aware default country) and/universities/[slug](tabs: Overview/Posts/Forums/Courses/Members/Reviews/Compare) if not present.
6. Standard Patterns
- Skeletons:
{#if loading}<Skeleton/>{:else if error}<ErrorState/>{:else if empty}<EmptyState/>{:else}...{/if}— skeleton shape matches real content - Optimistic UI with rollback for reactions/bookmarks/follows
- Tailwind v4: remove
@apply,theme(),dark:variant - i18n sweep: hardcoded strings →
$t(), keys inen.json+fr.json - A11y:
<div onclick>→<button>,aria-labelon icon buttons,alton images, visible focus rings - Types: eliminate
any, derive from API response types V2 main app phases (33–38): Identity Tools UI (Phase 33) → Jobs/Gamification/Referral (Phase 34) → Newsletter/Import/Travel (Phase 35) → QA (Phase 36) → Community Features UI (Phase 37) → Mentorship Matching UI (Phase 38). SeeROADMAP-MAIN.mdfor task breakdown.
V2 community features UI (Phase 37, §§79–89, §98): Community Story Wall (§79 — filterable testimonials by origin/destination/visa/profession), Destination Wiki (§80 — collaborative versioned KB pages with reputation-gated editing), Scam Alert Board (§81 — moderated scam reporting with subscriptions), Japa Planning Groups (§82 — private peer groups with milestones and check-ins), Visa Timeline Tracker (§83 — personal milestone logging with anonymous sharing), Community Digest Widget (§84 — auto-generated digest), Mutual Aid Board (§85 — Needs/Offers/Skill Swaps), Community Calendar (§86 — institutional dates calendar), Japa Stage Profiles (§87 — seven-stage relocation journey on profiles), Ask-an-Expat AMA (§88 — specialized forum AMA threads), Achievement Feed (§89 — opt-in milestone feed), Service Directory (§98 — geo-indexed business directory). All community feature pages must follow the geo-aware tool pattern: destination country selector is the first input, no hardcoded nationality, ?dest= filter on list endpoints.
V2 mentorship UI (Phase 38, §102, ADR-110): Mentor browsing/search, mentor profile pages, mentorship request flow, incoming/outgoing requests management, connection active/complete/cancel flows. Match scoring display (60% keyword overlap + 40% pgvector cosine similarity). DM auto-open on connection accept (§48).
V2 tool pages on main app (/tools/*): Visa Checklist, Readiness Assessment, Cost of Living, Scholarship Finder, Remittance Rate Tracker, JapaBot (full-page). Each tool is also available at its own domain/subdomain via apps/tools (§78) — the main app renders these within the community layout; apps/tools renders them tool-first without community nav.
V2 Feature Areas (Implement Only After Corresponding Backend Phase Is Complete)
| Feature | Backend phase | Key sections | Gates |
|---|---|---|---|
| JapaBot (RAG-grounded) | Phase 41 | §69 | /ai/chat amended |
| AI Content Studio (admin) | Phase 42 | §75 | studio.* RBAC |
| Participation queue (admin) | Phase 42 | §76 | participation.review RBAC |
| Visa Checklist | Phase 43 | §70 | checklist.use RBAC |
| Readiness Assessment | Phase 43 | §71 | assessment.take RBAC |
| Cost of Living Calculator | Phase 43 | §72 | col_calculator.use RBAC |
| Scholarship Finder | Phase 43 | §73 | scholarship.browse RBAC |
| Remittance Rate Tracker | Phase 44 | §74 | remittance.view RBAC |
| Referral system | Phase 45 | §60 | referral.use RBAC |
| Self-serve ads | Phase 45 | §61 | ads.self_serve.create RBAC |
| Newsletter | Phase 45 | §62 | newsletter.subscribe RBAC |
| Jobs board | Phase 45 | §63 | jobs.browse RBAC |
| Gamification | Phase 45 | §64 | gamification.view RBAC |
| Content import | Phase 46 | §65 | import.use RBAC |
| Advanced analytics | Phase 46 | §66 | analytics.advanced RBAC |
| Travel search | Phase 46 | §67 | travel.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.
5d. V2 Community Features & Mentorship — Refactoring Notes (Phases 37–38, §§79–102)
Apply Geo-Aware Tool Pattern to Existing Pages That Hardcode Nationalities
- Identify: grep for hardcoded nationality strings, country code arrays, or
?nationality=params in existing pages (especially pre-v2 community surfaces, forum filters, profile filters, or any page that filters by origin country). Any inlineconst countries = [...]or hardcoded"Nigerian"/"Ghanaian"labels are candidates. - Refactor: replace hardcoded nationality arrays with
GET /api/v1/geo/countriesfetched inload(). Replace?nationality=params with?dest=as the primary filter axis. Add a destination country selector as the first input on the page (Bits UI<Select.Root>or<Combobox.Root>). - Origin as secondary: where origin filtering is still needed (e.g. Story Wall §79), keep it as a secondary filter — but destination country is always first and primary.
- Pre-select from preference: if the user has
content_country_preference(ADR-064), pre-select the destination selector to that value; explicit selection always wins.
Ensure New Community Feature Pages Use Svelte 5 Runes (Not Svelte 4 Patterns)
- Identify: audit all files under
$lib/components/community/and/community/*routes for Svelte 4 patterns:export let,$:reactive statements,on:click,createEventDispatcher, writable stores for local UI state. - Refactor: apply the Svelte 4 → 5 migration table (Section 1):
export let story→let { story } = $props()$: filtered = items.filter(...)→let filtered = $derived(items.filter(...))$: { sideEffect() }→$effect(() => { ... })on:click={...}→onclick={...}createEventDispatcher()→ callback props (onaccept,ondecline,oncomplete)writable(false)for modal/panel open state →let open = $state(false)
- Verify: no writable stores for local UI state in new community components — use
$state(). Shared cross-component state that genuinely needs a store is fine, but local UI state (modal open, selected tab, filter values) should be$state.
Migrate Community Feature Charts to LayerChart 2.0.1
- Identify: any chart in community feature pages (Visa Timeline Tracker §83 milestone progress, Planning Groups §82 milestone charts, Achievement Feed §89 stats, Service Directory §98 analytics) built with Chart.js, raw D3, canvas, inline SVG, or any non-LayerChart library.
- Refactor: rewrite in LayerChart (pinned
layerchart@2.0.1, prefer high-level compound charts):- Milestone progress over time →
LineChartorAreaChart - Achievement stats breakdown → horizontal
BarChart - Service Directory category distribution → horizontal
BarChart - Planning Group participation trends →
AreaChart
- Milestone progress over time →
- Rules: colors via
var(--chart-*)/var(--color-*)only (dark-mode safe) · data from API (Rule 16) · fixed-height container · per-chart skeleton · convert API date strings toDateobjects · remove old chart library frompackage.jsonif unused after migration. - Do not confuse LayerChart's
<Tooltip.Root>with Bits UI's<Tooltip.Root>— check the import source.