agenta-ai / mobile-app-structure

Mobile app structure

The source of truth for how code is organized in web/mobile. Load it before
creating any file there.

Layout

web/mobile/
  src/
    pages/                    # Pages Router route shells ONLY — no logic, no layout JSX
    features/
      <feature>/              # e.g. sessions/, chat/, agents/, settings/, nav/
        <Component>.tsx       # one component per file, named export = file name
        use<Thing>.ts         # feature hooks and plain .ts helpers sit beside the components
        states/               # designed states for this feature
          <X>Skeleton.tsx     # mirrors the final layout geometry (no shift on swap)
          <X>Empty.tsx        # designed empty state with a call to action
          <X>Error.tsx        # error + retry affordance; preserves user input
    components/               # app-wide shells: AgentaLogo, ContentRail, PageTitle,
                              #   ScreenScaffold, StatusTag
      ui/                     # local shadcn registry components (see mobile-shadcn-conventions)
    lib/                      # cn util, motion presets, api glue, context resolution
    styles/                   # globals.css, theme.generated.css (generated)
  scripts/                    # generate-shadcn-tokens.ts (token bridge)

Rules

• Pages are thin shells. A page file resolves route params and renders one
  feature screen component. Anything else belongs in features/.

• One component per file. No secondary exported components; small private
  helpers inside a file are fine if they never leave it. The one tolerated
  exception is a feature's grouped states file (ChatStates.tsx,
  HomeStates.tsx, ObservabilityStates.tsx, OrganizationStates.tsx), which
  exports a few small state components together. New states get their own file.

• Every data-bearing component has designed states. Before writing the
  happy path, create the states/ siblings (skeleton, empty, error). A screen
  is not done if any of its states is a browser default or an unstyled string.
  Features with no data-bearing screens of their own (app/, context/,
  nav/) have no states/ folder.

• Data flow: components get data via hooks from @agenta/* packages
  (@agenta/entities, @agenta/shared, @agenta/chat, @agenta/sessions, ...)
  or thin fetchers in lib/. Many screens compose ready-made UI from the
  @agenta/*-ui packages; check there before building a surface from scratch. NEVER import @/oss/*, @agenta/oss, @agenta/ee — the mobile
  app has zero app-layer imports (lint enforces this).

• No provider fleet. _app.tsx stays minimal and mounts
  features/app/AppProviders.tsx (query client, jotai store, context sync,
  auth gate, entity modals). Add a provider only when a concrete feature needs it,
  scoped as narrowly as possible.

Adding a new feature (checklist)

1. Create src/features/<feature>/ with the screen component.
2. Create states/ siblings for every data-bearing component.
3. Add the route shell in src/pages/ that renders the screen.
4. Use useMotionPresets() for any transitions (see mobile-motion-patterns).
5. pnpm --filter @agenta/mobile lint && pnpm --filter @agenta/mobile types:check.