jc-mobile-audit
Use when performing a comprehensive quality audit of the JapaConnect Flutter mobile app (apps/mobile) before merge or release. Verifies the v2.1 screen contract, API-Readiness Gate, Rule 16, feature m
SKILL.md.claude/skills/jc-mobile-audit/SKILL.md
GitHubJapaConnect Mobile App — Audit Skill
You are auditing the Flutter mobile client before merge or release. The audit cross-checks apps/mobile/ and packages/japaconnect_core/ against the JEOS specs: sections/77-flutter-mobile-app.md, adr/ADR-067-flutter-mobile-app.md, adr/ADR-074-flutter-mobile-app-surface.md, adr/ADR-113-mobile-framework-agent-ease-tradeoff.md, AGENTS.md Rule 16, and conventions/api-routes-catalog.md.
Pre-requisites
apps/mobile/andpackages/japaconnect_core/exist. If not, the audit stops: the mobile app is not implemented.flutter analyzepasses with zero errors (warnings are acceptable if documented).flutter testpasses.- The backend is running so live API routes can be probed.
1. API-Readiness Gate
For every screen in the v2.1 contract (ADR-074 §5), verify:
- The screen exists in
lib/features/<feature>/screens/. - The screen consumes API endpoints documented in
conventions/api-routes-catalog.md. - Every endpoint the screen calls returns a non-404 response under correct auth.
- If a required endpoint is missing, record it as a backend gap, not a frontend gap.
Launch-screen checklist:
- Auth/onboarding, home feed, discover, blog, guides, comparisons, forum, JapaBot, spaces, follow/social, notifications, DMs, Japa Academy, profile, settings, wallet, bookmarks, badges/challenges/leaderboard, jobs finder.
V2 tool-screen checklist (only required as their backend phases complete):
- Visa Checklist, Readiness Assessment, Cost of Living, Scholarship Finder, Remittance Rate Tracker.
Out-of-scope screens (must NOT exist in apps/mobile/):
- Admin Panel, Control Panel, AI Content Studio, Persona management, Creator/Instructor dashboard.
2. Rule 16 — No Hardcoded Data
Search apps/mobile/lib/features/ for:
- No mock user objects (e.g.,
const user = User(name: 'Test', ...)). - No static option lists that should come from API (countries, currencies, languages, categories, nav items).
- No hardcoded content or feed data.
- No static feature flags — must come from
GET /api/v1/feature-flags. -
pubspec.yamldoes not contain runtime API data.
Permitted hardcoded values:
- Pure client constants (animation durations, padding tokens, debounce delays).
- Asset paths and l10n keys.
- Environment/build-time constants (base URL, build flavor).
3. Feature Module Isolation
For each feature module in lib/features/:
- The feature has its own
screens/,providers/,services/, andwidgets/. - The feature depends only on
japaconnect_coreand Flutter SDK packages. - No imports from sibling
features/modules. - No service layer directly imports another feature's service.
- Route definitions live in
app/router.dartor inside the feature's ownroutes/directory.
4. japaconnect_core Package Audit
4.1 API client
- Generated from the OpenAPI spec (§47) and the generation command is documented in
packages/japaconnect_core/README.mdorMakefile. - No raw
httpordiocalls outside the generated client. - Base URL is configurable (env or
system_settings). -
Authorization: Bearer <access_token>sent on authenticated requests. -
X-Device-Idheader sent on every request. - 401 triggers one refresh-retry cycle.
- Standard error format is parsed into typed exceptions.
4.2 Auth service
- Access token is kept in memory only.
- Refresh token and device ID are stored in
flutter_secure_storage. - Device ID is a stable UUID generated on first install.
- TOTP prompt wires
POST /api/v1/auth/totp/verify. - Logout calls
POST /api/v1/auth/logoutandDELETE /api/v1/me/devices/:device_id. - No secret values are logged or printed.
4.3 Models
- Every model has
fromJson/toJson. - Nullable fields match the API schema.
- No
dynamicorMap<String, dynamic>leaking into feature code. - Types are generated and checked against the OpenAPI spec.
4.4 Widgets
- Shared widgets exist:
EntityCard,FeedCard,AvatarWidget,LoadingShimmer. - Design tokens exist:
JcColors,JcTypography,JcSpacing. - Shared widgets are used in feature screens; no duplicate card implementations.
5. Authentication & Session Audit
- No SameSite cookie usage.
- CSRF-immune Bearer token only.
- Login/Register/Forgot/TOTP/Onboarding screens map to verified routes.
- Session scoping is per device (
jc:refresh:{user_id}:{device_id}pattern, §02). - Logout invalidates the current device only, not all sessions.
6. Push Notification Audit
-
firebase_messaging(or APNs equivalent) is configured. -
POST /api/v1/me/devicesis called on token registration. -
DELETE /api/v1/me/devices/:device_idis called on logout. - Foreground, background, and terminated message handlers are wired.
- Deep links from push payloads route correctly (
go_router). - Backend
notification:send_pushAsynq task is wired and enqueued. -
device_tokens.is_activeis set tofalseon invalid-token feedback (FCM/APNs).
7. Offline / Caching Policy
- Feed and content show last-loaded state while refresh runs.
- No SQLite / Hive dependency.
- Optimistic UI is implemented for reactions, follows, bookmarks and reverts on API error.
- Compose drafts are persisted in
flutter_secure_storage. - Images are cached via
CachedNetworkImageor equivalent.
8. UI / UX Audit
- App shell follows the mobile design: bottom nav, context top app bar, search delegate.
- Feed uses
FeedCardconsistently across all content types. - Screens adapt to 320dp–720dp widths.
- Dark mode tokens applied via theme data.
- Loading, empty, and error states are present on all data-driven screens.
- Pull-to-refresh and infinite scroll work on feed/list screens.
- Tap targets are at least 48×48dp.
- Screen readers / TalkBack labels are set for icon-only buttons.
9. Performance Audit
- No unbounded widget rebuilds.
- Images are constrained and cached.
- Lists are paginated from the API, not loaded all at once.
- No heavy computation inside
buildmethods. -
constconstructors are used for static subtrees.
10. Test & Build Audit
-
flutter analyzereturns zero errors (warnings documented). -
flutter testpasses. - Android build succeeds:
flutter build apk --flavor devorflutter build appbundle. - iOS build succeeds on macOS:
flutter build ios --no-codesign(simulator) or with provisioning (device). - No debug code (print statements, fake data, commented-out routes) is committed.
11. Security Audit
- No secrets in
pubspec.yamlor Dart code. - Access token is not written to secure storage, logs, or crash reports.
- Refresh token is not logged.
-
flutter_secure_storageis used for refresh token and device ID. - Certificate pinning is not bypassed.
- No
allowClearTextTrafficin release AndroidManifest (unless a dev flavor).
Audit Output
Write findings to .jeos/audit/mobile-audit.md using the standard audit report format:
## 1. API-Readiness Gate
| Screen | Primary Endpoint | Status | Gap |
...
## 2. Rule 16 Findings
...
## 3. ...
## Summary
- Total bugs: <n>
- Conformance: <n> ✅ / <n> ⚠️ / <n> ❌
- Blockers: <list>