Skip to content

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

jc-control-develop

Unverified

Use when building new pages or components for the JapaConnect Control Panel (apps/control, port 3002, SPA). Covers infrastructure dashboards with LayerChart, the RBAC CRUD Gate, the mandatory DataTable spec, API key/extension/settings/job-queue patterns, and safe polling.

JapaConnect Control Panel — Development Skill

Operator-facing SPA (adapter-static, super_admin + control_panel.access only). API base /api/v1/control/*. Design: dev.to admin + Vercel dashboard; dark mode default; monospace for IDs/keys/JSON.

⛔ GATE 1 — API-READINESS

Identical to jc-admin-develop Gate 1: list endpoints → verify each → any missing: STOP + ⚠️ MISSING BACKEND API ROUTES alert. Never mock.

⛔ GATE 2 — RBAC CRUD (Non-Negotiable)

Super-admin full CRUD on every Control Panel entity (API keys, OAuth clients, extensions, tenant sites, system settings, permission nodes, webhook endpoints, backup configs). Before implementing any entity page, verify List/Get/Create/Update/Delete + state routes (activate/deactivate, enable/disable, revoke/restore) all exist and are RBAC-gated. Any missing: STOP + ⛔ MISSING RBAC CRUD ENDPOINTS alert (format in jc-admin-develop).

📋 DATATABLE SPEC — Same Mandate as Admin

Every entity list (API keys, sites, extensions list-view, failed jobs, audit log, impersonation log) uses the full spec from jc-admin-develop: sortable · searchable · filterable · paginated · action column (View/Edit/Delete + state actions like Revoke, Enable/Disable) · bulk actions · Create button on non-readonly entities. Readonly entities here (audit log, impersonation log, webhook delivery log, job history): action column MUST include Delete/Remove/Clear per row + a "Clear all / Clear older than…" bulk control.

LayerChart — Infrastructure & Ops Visualization (Mandatory)

All Control Panel dashboards render metrics with LayerChart:

  • Health dashboard: per-service time-series sparklines (PG pool usage, Valkey memory, Meilisearch index size) — <Chart> + <Area>/<Spline>
  • Job queue monitor: queue depth over time per tier (<Spline> × 3, legend), failed-vs-processed stacked <Bars>
  • AI cost monitoring: daily spend <Bars> + cumulative <Spline>
  • Traffic/platform metrics: request volume, error rate <Area>
  • Rules: colors var(--color-success|warning|danger|primary) only · fixed-height containers · data from /api/v1/control/* endpoints · skeletons · live charts append new points on each poll tick

Key Page Patterns

API Keys: DataTable · create in <Dialog.Root> with scope multi-select · show key ONCE in reveal dialog (copy button + <Tooltip.Root> "Copied!") · never keep raw key in $state after close (onOpenChange clears) · Revoke = state action with confirmation. Extensions: card grid + <Toggle.Root> per extension · toggle disabled while PATCH in-flight · optimistic + rollback · disabling with active content → warning dialog · Configure → manifest-driven settings dialog. System Settings (85 keys): <Tabs.Root> per category · type-appropriate inputs · JSON values validated before save · deep-equality dirty tracking ($derived(JSON.stringify(a)!==JSON.stringify(b))) · unsaved banner + beforeNavigate guard · batch PATCH with [{key,value}].

Geo-aware personalization (ADR-064) settings:

  • geo_personalization.enabled (boolean, default true) — the killswitch. When false, all surfaces fall back to global ranking. Prominently placed in the settings UI with a warning dialog on disable ("This will disable geo-personalized content for all users").
  • Feed geo boost cap, search geo weight multiplier — numeric settings, tuneable without deploy.

Japa Academy (ADR-063) settings:

  • university.default_commission_pct, university.verified_tier_commission_pct, university.partner_tier_commission_pct — revenue split percentages per tier.
  • academy.pro_stream_rate_kobo — per-Pro-learner stream rate for creator compensation.
  • university.payout_min_threshold_kobo — minimum payout amount; below this, payouts roll to next period.
  • university.payout_period_days — payout cycle length.
  • university.surface_domain — the Japa Academy branded domain (default academy.japa.to). Changing this affects host detection in the Learn app.

Job Queue: tabs Critical/Default/Low · stats + failed-jobs DataTable (retry action) · poll 15s. Health: service cards + LayerChart sparklines · poll 30s. Safe polling (mandatory pattern):

$effect(() => {
  const tick = async () => { try { const r = await fetch(url); if (r.ok) data = await r.json(); } catch {} };
  tick();
  const id = setInterval(tick, 30_000);
  return () => clearInterval(id);
});

SPA Architecture & Stack

Same as jc-admin-develop: ssr=false, auth guard verifying BOTH session AND control_panel.access node, $effect fetching, Svelte 5 Runes, Bits UI dot-notation, Tailwind v4, $t() i18n, no AI attribution. Environment badge (PRODUCTION/STAGING) in top bar.

Deliverables Per Task

  1. Gate 1 + Gate 2 output · 2. +page.svelte (full-spec DataTable / LayerChart dashboard / settings pattern) · 3. dialogs & components · 4. types · 5. every /api/v1/control/* route confirmed V2 control panel: No new control panel pages for v2 features — v2 features are managed in the Admin panel. Control panel remains super-admin infrastructure (tenants, system settings, feature flags). Update system_settings pages to expose the new v2 keys (settings are already stored; control panel just needs form fields for them).

V2 system settings (JEOS v1.22.0–v1.23.1, §§79–102): The system_settings page must expose form fields for:

  • 14 tool-domain keys for §§79–101 functional tools: {slug}.subdomain and {slug}.custom_domain per tool (visa-route, embassy-alerter, arrival-checklist, processing-tracker, credential-checker, cv-formatter, housing-guide, attestation-guide, language-test, tax-calculator, community-locator, plus community feature domains). These feed the Tools app host-detection map.
  • mentorship.max_capacity — maximum mentee capacity per mentor (§102, ADR-110).
  • Other feature-specific settings for §§79–102 community features and functional tools.
  • Total system settings count is now ~187 (up from 85). Update the settings tab categories to include a "V2 Tools" category for the tool-domain keys.

V2 feature flags (§§79–102): ~24 new feature flags for v2 features:

  • ~22 flags for §§79–101 community features and functional tools (one per feature, plus sub-feature flags)
  • 2 flags for mentorship (§102, ADR-110): mentorship.enabled and mentorship.matching.enabled
  • Feature-flag middleware returns 404 (not 403) when disabled (ADR-042) — verify the control panel feature-flag toggle UI communicates this behavior
  • Total feature flags count is now ~24 (up from previous count)

Geo-aware tool pattern & ADR-088 verification in control panel: When adding settings forms for v2 functional tools, verify:

  • Tool-domain settings (subdomain/custom_domain) are string fields with domain validation
  • Feature flags for v2 tools are boolean toggles with the ADR-042 404 behavior documented in the field help text
  • ADR-088 AI content generation columns (ai_generated, ai_model, hitl_reviewed_by, ai_generated_at, is_japabot_indexed) are backend concerns but the control panel should expose any related settings (e.g. AI model selection, HITL review workflow toggles)

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.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexUnverifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall