AlexandrAI AGENTS.md
agents-md

AB Mobile Agent Guide

Project-specific AGENTS.md guidance for the AB Expo mobile app, screen and hook boundaries, API configuration, media handling, and verification workflow.

AGENTS.md

Guidance for coding agents working on AB Mobile. This repo is the Expo React Native client for AB and depends on a separately running AB API service.

Project overview

ab-mobile is a React Native app built with Expo. It owns the mobile experience, local presentation state, native integrations, and client-side API calls. The API base URL is supplied through EXPO_PUBLIC_AB_API_URL; do not hardcode a host or port in source.

The app uses Expo modules for auth session, crypto, file system, haptics, images, image picking, local authentication, notifications, secure storage, tracking transparency, video, and web browser interactions.

Setup commands

bashcd <project-root>/ab-mobile
npm install
EXPO_PUBLIC_AB_API_URL=<AB_API_URL> npm start

Platform-specific launch commands are:

bashnpm run ios
npm run android

When testing on a physical device, provide a reachable API URL through the environment. Do not rely on a web fallback for device testing.

Code organization

  • App.tsx is the orchestration shell for providers, navigation, and wiring. Keep feature logic out of it.
  • Types belong in src/types/.
  • Localized copy belongs in src/i18n/.
  • Pure helpers belong in src/utils/.
  • Tokens and StyleSheets belong in src/theme/.
  • Reusable presentational components belong in src/components/.
  • Screens belong in src/screens/XScreen.tsx.
  • Stateful domain hooks belong in src/state/useX.ts.
  • API calls and API-facing types belong in src/abApi.ts.

A new screen normally means a new screen file plus a new state hook; App.tsx should only wire them together.

Testing and verification

bashnpm test
npm run typecheck
npm run check:size
maestro test maestro/ab-vote-flow.yaml

Jest uses jest-expo and ignores generated or tool-specific directories. Maestro requires a running app and a configured device or simulator.

Security and media

Do not bundle base64 image or video bytes. Use opaque media references and the server-provided upload flow. Store secrets only through the platform mechanisms already in the app; do not add ad hoc plaintext persistence.

Commit and PR rules

Keep UI changes componentized, add tests for new hooks or screens, and mention the API assumptions used during verification. Run npm test and npm run typecheck before marking work done.