jedafe/japa / .claude/skills/jc-mobile-develop
jc-mobile-develop
UnverifiedUse when building new pages, components, or feature modules for the JapaConnect Flutter mobile app (apps/mobile, Dart, v2.1 fast-follow). Covers the shared japaconnect_core package, device-scoped JWT auth, Riverpod state, the v2.1 screen contract, push notification wiring, offline/caching policy, and the API-Readiness Gate per §77, ADR-067, ADR-074, and ADR-113.
JapaConnect Mobile App — Development Skill
You are building the native iOS + Android Flutter client for JapaConnect. One Dart codebase in apps/mobile/, one shared Dart package in packages/japaconnect_core/. The app is a thin client over /api/v1. All data comes from the Go backend. The web surfaces are the source of feature truth — the mobile app renders the same features with a touch-first shell.
⛔ API-READINESS GATE — RUN BEFORE ANY IMPLEMENTATION
Before writing a single line for any screen or feature module:
- List every API endpoint the screen will consume (reads + mutations).
- Verify each exists in
.jeos/conventions/api-routes-catalog.mdor probe the running backend (curl -s http://localhost:8080/api/v1/...). - If ANY endpoint is missing or returns 404: STOP. Do not implement. Do not mock. Do not hardcode placeholder data. Output the alert:
⚠️ MISSING BACKEND API ROUTES — mobile implementation paused
Feature: [feature name]
Missing routes:
- GET /api/v1/...
Action needed: implement these routes in the Go backend before mobile work continues.
Rule 16 (no hardcoded data) applies to Flutter exactly as to SvelteKit. No mock user objects, no static option lists, no hardcoded navigation. Every list, every option, every user-owned value must come from the API.
Non-Negotiable Stack
- Flutter (stable channel), Dart, Bun is not used in Flutter — use
flutterCLI anddartCLI directly. - State: Riverpod (preferred) or equivalent; no
setStatesoup in feature screens. - Auth:
flutter_secure_storage(refresh token + device ID), in-memory access token,X-Device-Idheader on every request. - HTTP: the typed
japaconnect_coreAPI client only — no rawhttpordioin feature code. - Models: typed Dart models in
japaconnect_core/lib/models/generated from the OpenAPI spec (§47). - UI: JapaConnect design tokens (colors, typography, spacing) in
japaconnect_core/lib/widgets/. Shared components:EntityCard,FeedCard,AvatarWidget,LoadingShimmer. - Images:
CachedNetworkImage(or equivalent) for remote images; placeholder + error widget. - Push:
firebase_messaging(Android) /flutter_apnsorfirebase_messagingiOS with APNs. Device token registered viaPOST /api/v1/me/devices. - Charts:
fl_chartfor mobile analytics (do not import web-only chart libraries). - Navigation:
go_routerfor deep links and shell routing.
Forbidden in production Flutter code:
- Raw
httpcalls inapps/mobile/lib/features/ - Hardcoded data that should come from the API (Rule 16)
- Storing access tokens in
flutter_secure_storageorSharedPreferences localStorage(no browser here)- AI attribution in comments or commit messages (Rule 17)
Repository Structure
apps/mobile/
pubspec.yaml # depends on japaconnect_core (path: ../../packages/japaconnect_core)
lib/
main.dart # entry point, ProviderScope, GoRouter
app/ # shell, theme, router, global providers
app_shell.dart
theme.dart # JapaConnect tokens
router.dart # go_router configuration
auth_guard.dart
features/ # each feature is self-contained
auth/
feed/
forum/
content/
tools/
spaces/
social/
learning/
profile/
gamification/
jobs/
packages/japaconnect_core/
lib/
api/ # generated typed client
auth/ # AuthService, token refresh, device ID
models/ # typed Dart models
widgets/ # shared UI primitives + design tokens
Every feature module owns its routes, screens, providers, and service layer. It depends only on japaconnect_core. No imports from sibling features/ modules.
The Mobile App Shell
- Bottom navigation (iOS + Android): Home, Spaces, Tools, Notifications, Profile. Center tab is a Compose FAB.
- Top app bar: context-aware; search opens a search delegate; avatar opens account menu.
- Home feed:
FeedCardlist, pull-to-refresh, infinite scroll (scrollController+ pagination from API). - Single-screen pattern: blog/guides/comparisons open as single scrollable pages; forums use a list-detail pattern; DMs use chat bubbles; JapaBot is a chat thread.
- Safe area + insets: respect
MediaQuerypadding andviewInsetsfor keyboards. - Dark mode: theme token toggled from
jc_theme(synced viaPATCH /api/v1/me/settings).
japaconnect_core — The Contract
API client (lib/api/client.dart)
Generated from the OpenAPI spec (§47). Every method maps to one /api/v1 route. It handles:
- Base URL from
JC_API_BASE_URLenv /system_settings - Bearer token injection from in-memory access token
X-Device-Idheader injection fromflutter_secure_storage- 401 → refresh token → retry with new access token (max 1 retry)
- Standard error format (
{ error: { code, message, status } }) → typed exceptions
Auth service (lib/auth/service.dart)
login(username, password)→POST /api/v1/auth/login; stores refresh token + device ID; keeps access token in memory.refresh()→POST /api/v1/auth/refreshwith refresh token; updates in-memory access token.logout()→POST /api/v1/auth/logout; deregisters push token (DELETE /api/v1/me/devices/:device_id); clears stored tokens.deviceId— generated UUID on first install, persisted influtter_secure_storage, sent asX-Device-Id.TOTPPromptwidget — shown when login response requires TOTP; callsPOST /api/v1/auth/totp/verify.
Models (lib/models/)
Typed Dart classes for all API entities: User, Content, Space, Guide, Assessment, Notification, Conversation, etc. Use freezed or hand-written fromJson/toJson. Every model property is nullable where the API schema is nullable.
Widgets (lib/widgets/)
EntityCard— generic list itemFeedCard— full feed card with avatar, name, space, content preview, engagement barAvatarWidget— rounded avatar with placeholder and errorLoadingShimmer— skeleton loadingJcErrorWidget— standard error state with retryEmptyState— illustration + message + CTAJcButton,JcIconButton,JcTextField,JcBadge,JcPill- Design tokens:
JcColors,JcTypography,JcSpacing— used by all feature screens.
Feature Module Pattern
To add a new mobile screen:
- Verify API routes exist (API-Readiness Gate).
- Create
lib/features/<name>/with the scaffold:screens/— one screen per routeproviders/— Riverpod providers (notifiers / async notifiers)services/— thin service callingjapaconnect_coreAPI clientwidgets/— private widgets used only by this feature
- Add routes in
app/router.dart. - Wire providers to
app/global providers only when truly global; prefer local scoping withProviderScope. - Use the shared widgets; never define a second
FeedCardinside a feature. - Add widget tests under
test/features/<name>/. - Run
flutter analyzeandflutter testbefore finishing.
Authentication & Onboarding
- Login, Register, Forgot, TOTP — use
auth/feature. - Onboarding wizard calls
GET /api/v1/onboarding/*and posts selections toPATCH /api/v1/me. - No browser cookies. CSRF exemption. All auth via Bearer token.
Push Notifications
- Request permission via
firebase_messaging. - On token refresh, call
POST /api/v1/me/deviceswith{ device_id, platform, token }. - Store the token locally only for re-registration; the backend owns the authoritative list (
GET /api/v1/me/devices). - On logout, call
DELETE /api/v1/me/devices/:device_id. - Foreground messages: show an in-app snackbar or update the notifications badge.
- Background/terminated: route via deep link (
/notifications,/messages/:id,/spaces/:slug, etc.).
Offline / Caching Policy
- Feed and content: in-memory Riverpod cache (or
Riverpodprovider state); show last-loaded state while refresh runs. - No local SQLite / Hive database (deferred to v3).
- Optimistic UI: reactions, follows, bookmarks update local state first and revert on API error with a snackbar.
- Compose drafts: small JSON blob in
flutter_secure_storage, restored on reopen. - Image cache:
CachedNetworkImagedisk cache.
V2.1 Screen Contract
Build order follows backend completion. Every screen below must have verified endpoints before implementation.
Launch screens (v1 endpoints — build first): Auth/onboarding, home feed, discover, blog, guides, comparisons, forum, JapaBot chat, spaces, follow/social, notifications, DMs, Japa Academy, profile, settings, wallet, bookmarks, badges/challenges/leaderboard, jobs finder.
V2 tool screens (add as backend phases 43–44 complete): Visa Checklist, Readiness Assessment, Cost of Living, Scholarship Finder, Remittance Rate Tracker.
Out of scope for mobile: Admin Panel, Control Panel, AI Content Studio, Persona management, Creator/Instructor dashboard.
Implementation Checklist
Before finishing any mobile feature, verify:
- All API routes exist and are called through
japaconnect_core - No hardcoded data that should come from the API
- Feature module is self-contained (no sibling imports)
-
X-Device-Idheader is sent on all authenticated requests - Access token is in memory only; refresh token + device ID in
flutter_secure_storage - Push token registration/unregistration is wired (if the feature triggers notifications)
- Optimistic UI has rollback on error
- Widget tests pass
-
flutter analyzepasses with zero issues - iOS Simulator and Android Emulator both render the screen without overflow
- Dark mode tokens are applied
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |