> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Project structure

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

## Setup and configuration

Before any step, read [Before you start](https://supastack.dev/docs/mobile/before-you-start.md) and [Terminal basics](https://supastack.dev/docs/mobile/terminal-basics.md). 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.

[Build your first mobile feature](https://supastack.dev/docs/mobile/first-feature.md)

- 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
```


## Next

[Build your first feature](https://supastack.dev/docs/mobile/first-feature.md)