Skip to content
supastack
Browse documentation
MobileExpo

For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/mobile/project-structure.md (or send Accept: text/markdown).

Project structure

Find the routes, the feature modules, and the boundary to the backend.

Ask about this guide
Open in

Setup and configuration

Before any step, read Before you start and Terminal basics. Open the supastack folder at its root — the folder containing package.json. A Mobile checkout contains apps/mobile plus the shared packages below; the All Platforms monorepo adds the Web backend and the Desktop shell alongside. An environment variable is a named setting stored in a local .env file or your hosting dashboard; restart the app after changing it, and keep server secrets out of EXPO_PUBLIC_ values.

1. Open apps/mobile/app/_layout.tsx in the editor — the root layout every screen shares.

2. Browse apps/mobile/src/ — one folder per feature area, each holding its logic and tests.

3. From the repository root run corepack pnpm --filter @supastack/mobile start and open the preview on your device.

The Expo app is organized as routes that call feature modules. Routes stay thin — they render screens; the logic they call lives under src/ with its tests beside it. Read AGENTS.md and .ai/PROJECT_CONTEXT.md before changing behavior; the .ai/ mirror docs record decisions that are not visible from a file alone.

apps/mobile/app/          Expo Router routes — sign-in, onboarding, invite, paywall
apps/mobile/app/(app)/    Signed-in screens — home, chat, notifications, settings, content, commerce, assistant
apps/mobile/src/          Feature modules — auth, api, purchases, offline, push, ui, theme, i18n
packages/ui-native/       Shared native view-models
packages/design-tokens/   Shared theme tokens
apps/mobile/app.config.ts Scheme and allowed-origin derivation
apps/mobile/eas.json      EAS build and submit profiles
docs/                     Runbooks incl. store submission
.agents/skills/           Task guides for coding agents

Where a change belongs

Before editing, decide which folder owns the change. The rule of thumb: a route file only renders; reusable logic lives in a src/ module; anything the server must decide never enters the app.

  • A new signed-in screen → apps/mobile/app/(app)/ for the route plus apps/mobile/src/<feature>/ for its logic.
  • A new pre-auth or standalone screen → apps/mobile/app/ outside the (app) group.
  • A call to the backend → apps/mobile/src/api/client.ts — extend the typed client rather than fetching ad hoc.
  • A visual shared between screens → apps/mobile/src/ui/ primitives; a cross-platform view-model → packages/ui-native/.
  • Colors, spacing and dark/light values → apps/mobile/src/theme/ backed by packages/design-tokens/.
  • A new translation key → all four catalogs under apps/mobile/src/i18n/.
  • Anything server-side — data, permissions, provider calls → the Web backend repository, which is a separate checkout for Mobile-only purchases.

Implementation workflow

Start at the route file, follow the feature module it renders, then the API client call — the server decides ownership; the app never re-derives it. The add-a-mobile-screen skill in .agents/skills/ walks this same order.

Run the package tests and typecheck after editing a shared package or the API client; the client must keep the same contract the backend serves.

Verification and troubleshooting

If expo start reports a missing module, run the install command from the repository root — the app folder alone cannot resolve workspace packages. If a screen appears unstyled, check that it composes src/ui primitives instead of raw elements with hardcoded colors.

corepack pnpm --filter @supastack/mobile test
corepack pnpm --filter @supastack/mobile typecheck