> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipnative.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Structure

> Understand the Shipnative monorepo layout

Shipnative is a **monorepo** - one repository with multiple apps and shared packages. Here's how it's organized.

## What You Cloned

When you run `git clone https://github.com/shipnativeapp/shipnative.git`, you get this structure:

```
shipnative/                      # ← This is the monorepo (what you cloned)
│
├── apps/
│   ├── app/                     # React Native mobile app (Expo)
│   └── web/                     # Marketing landing page (Vite)
│
├── convex/                      # Convex backend (if using Convex)
│   ├── schema.ts               # Database schema
│   ├── auth.ts                 # Auth configuration
│   └── ...                     # Your custom functions
│
├── supabase/                    # Supabase config (if using Supabase)
│
├── vibe/                        # AI context files for vibecoding
│   ├── SERVICES.md             # Service architecture overview
│   ├── MOCK_SERVICES.md        # How mock mode works
│   └── CONVEX.md               # Convex-specific patterns
│
├── AGENTS.md                    # AI context (tech stack, directory map)
├── package.json                 # Monorepo root
├── turbo.json                   # Turborepo configuration
└── yarn.lock                    # Dependency lock file
```

<Note>
  **This is what matters to you as a Shipnative customer.** Everything else you might see in external documentation or development setups is for Shipnative's internal development and maintenance.
</Note>

## The Two Main Apps

### Mobile App (`apps/app/`)

Your primary React Native application. This is where you'll spend most of your time building features.

```
apps/app/
│
├── app/                         # Source code
│   ├── screens/                # Screen components
│   ├── components/             # Reusable UI components
│   ├── navigators/             # React Navigation setup
│   ├── stores/                 # Global state (Zustand)
│   ├── services/               # External services (Supabase, RevenueCat, etc.)
│   │   └── mocks/              # Mock implementations
│   ├── hooks/                  # Custom React hooks
│   │   ├── supabase.ts         # useSupabaseAuth hook
│   │   ├── convex.ts           # useConvexAuth hook
│   │   └── useAppAuth.ts       # Backend-agnostic auth hook
│   ├── providers/              # React providers
│   │   └── BackendProvider.tsx # Supabase or Convex provider
│   ├── utils/                  # Helper functions
│   ├── theme/                  # Design system
│   │   └── unistyles.ts        # Theme configuration
│   ├── config/                 # App configuration
│   │   └── env.ts              # Environment & backend detection
│   └── app.tsx                 # App entry point
│
├── assets/                      # Images, fonts, etc.
├── .env                         # API keys (git-ignored)
├── app.json                     # Expo configuration
├── index.tsx                    # Entry point
└── package.json                 # App dependencies
```

**Key folders to know:**

<AccordionGroup>
  <Accordion title="app/components/ - UI Components">
    Pre-built components like `Button`, `Card`, `TextField`, etc. Use these instead of building from scratch.

    ```typescript theme={null}
    import { Button, Card, Text } from '@/components'
    ```
  </Accordion>

  <Accordion title="app/hooks/ - Auth Hooks">
    Native auth hooks for each backend, plus a unified hook.

    ```typescript theme={null}
    // Backend-specific (recommended for full control)
    import { useSupabaseAuth } from '@/hooks/supabase'
    import { useConvexAuth } from '@/hooks/convex'

    // Backend-agnostic (for shared components)
    import { useAppAuth } from '@/hooks/useAppAuth'
    ```
  </Accordion>

  <Accordion title="app/stores/ - Global State">
    Zustand stores for app-wide state like subscriptions and preferences.

    ```typescript theme={null}
    import { useSubscriptionStore } from '@/stores/subscriptionStore'

    const { isPro, checkEntitlement } = useSubscriptionStore()
    ```
  </Accordion>

  <Accordion title="app/services/ - External APIs">
    Service clients for Supabase, RevenueCat, PostHog, etc. Automatically uses mocks when API keys are missing.

    ```typescript theme={null}
    import { supabase } from '@/services/supabase'
    ```
  </Accordion>

  <Accordion title="app/theme/ - Design System">
    Unistyles theme with colors, spacing, typography. Always use theme values instead of hardcoding.

    ```typescript theme={null}
    import { useUnistyles } from 'react-native-unistyles'

    const { theme } = useUnistyles()
    theme.colors.primary
    theme.spacing.md
    ```
  </Accordion>
</AccordionGroup>

### Convex Backend (`convex/`)

If using Convex, your backend functions live at the root level:

```
convex/
│
├── _generated/                 # Auto-generated types (don't edit)
├── schema.ts                   # Database schema
├── auth.ts                     # Auth configuration
├── users.ts                    # User queries and mutations
├── realtime.ts                 # Realtime features (chat, presence)
└── ...                         # Your custom functions
```

### Marketing Page (`apps/web/`)

A Vite + React application for your app's marketing/landing page.

```
apps/web/
│
├── src/
│   ├── app/                    # Next.js App Router pages
│   ├── components/             # React components
│   └── lib/                    # Utilities
│
├── public/                      # Static assets
└── package.json                 # Web app dependencies
```

## Documentation Files

The root directory contains markdown documentation for developers:

| File                 | Purpose                         |
| -------------------- | ------------------------------- |
| `README.md`          | Quick start and overview        |
| `SUPABASE.md`        | Authentication & database setup |
| `MONETIZATION.md`    | RevenueCat payments setup       |
| `ANALYTICS.md`       | PostHog & Sentry setup          |
| `NOTIFICATIONS.md`   | Push notifications setup        |
| `DEPLOYMENT.md`      | App store deployment guide      |
| `TROUBLESHOOTING.md` | Common issues and solutions     |
| `DESIGN_SYSTEM.md`   | Design tokens and patterns      |
| `BACKEND.md`         | Database schema                 |

## The AI Documentation System (Layered Context)

Shipnative uses a **Layered Context** architecture. This ensures that AI agents get the right amount of information at the right time, minimizing "token waste."

### 1. Discovery Layer (`AGENTS.md`)

Follows the [AGENTS.md standard](https://agents-md.com). These are "Front Desk" files that agents read first to understand the directory structure and constraints.

* **Root**: `shipnative/AGENTS.md`
* **Mobile**: `apps/app/AGENTS.md`
* **Web**: `apps/web/AGENTS.md`

### 2. Specification Layer (`vibe/` folders)

These are the **"Brain"** of the project, containing deep-dive technical specs.

* **App Logic**: `apps/app/vibe/` (Styling, Architecture, Screen Templates)
* **Infrastructure**: `vibe/` (Service architecture, Mock mode, Convex patterns)

### 3. Tech Stack Rules (in `AGENTS.md`)

The root `AGENTS.md` contains the tech stack rules (e.g., "Always use Unistyles") that agents must follow.

***

## Configuration Files

### Root Level

* **`package.json`** - Monorepo dependencies and scripts
* **`turbo.json`** - Turborepo build configuration
* **`tsconfig.json`** - TypeScript configuration
* **`AGENTS.md`** - AI context (tech stack, directory map)
* **`.cursorrules`** - Points to AGENTS.md

### App Level (`apps/app/`)

* **`app.json`** - Expo configuration (app name, bundle ID, etc.)
* **`.env`** - Environment variables (API keys, backend provider)
* **`package.json`** - App-specific dependencies
* **`tsconfig.json`** - TypeScript configuration

### Convex Level (`convex/`)

* **`schema.ts`** - Convex database schema
* **`auth.ts`** - Auth configuration

## How the Monorepo Works

**Turborepo** manages the monorepo. When you run commands from the root:

```bash theme={null}
yarn dev              # Runs the mobile app (Expo) in dev mode
yarn app:ios          # Runs mobile app on iOS
yarn web              # Runs the marketing landing page (apps/web)
yarn app:web          # Runs the Expo web build of the app
yarn build            # Builds all apps
```

Each app can also be run independently:

```bash theme={null}
cd apps/app
yarn ios              # Run mobile app

cd apps/web
yarn dev              # Run landing page

# Convex dev server (from root)
npx convex dev        # Run Convex dev server (if using Convex)
```

## Where to Start

<CardGroup cols={2}>
  <Card title="For Vibecoders" icon="wand-magic-sparkles">
    Start in `apps/app/app/` - build screens and components. Let AI help you!
  </Card>

  <Card title="For Explorers" icon="compass">
    Browse `apps/app/app/components/` to see what's available, then check `apps/app/app/screens/` for screen examples.
  </Card>
</CardGroup>

## Finding What You Need

<AccordionGroup>
  <Accordion title="Where do I add a new screen?">
    Add it to `apps/app/app/screens/`. Then register it in `apps/app/app/navigators/AppNavigator.tsx` or `MainTabNavigator.tsx`:

    * For main flow screens: Add to `AppNavigator.tsx`
    * For tab screens: Add to `MainTabNavigator.tsx`
    * Example: `apps/app/app/screens/ProfileScreen.tsx`
  </Accordion>

  <Accordion title="Where do I create a new component?">
    Add it to `apps/app/app/components/`. Export it from `apps/app/app/components/index.ts` so others can import it easily.

    ```typescript theme={null}
    // In ProfileCard.tsx
    export const ProfileCard = () => { ... }

    // In index.ts
    export * from "./ProfileCard"
    ```
  </Accordion>

  <Accordion title="Where do I add global state?">
    Create a Zustand store in `apps/app/app/stores/`. Follow the pattern in existing stores like `subscriptionStore.ts`.
  </Accordion>

  <Accordion title="Where do I customize the theme?">
    Edit `apps/app/app/theme/unistyles.ts`. This file defines colors, spacing, typography, shadows, and all design tokens.
  </Accordion>

  <Accordion title="Where do I add backend logic?">
    **Supabase:** Use the Supabase client in `apps/app/app/services/supabase.ts` or create Edge Functions.

    **Convex:** Add functions to `convex/`. Create queries, mutations, and actions as needed.
  </Accordion>

  <Accordion title="Where do I modify auth?">
    **Supabase:** Check `apps/app/app/hooks/supabase.ts` for the `useSupabaseAuth` hook.

    **Convex:** Check `apps/app/app/hooks/convex.ts` for the `useConvexAuth` hook.

    **Backend-agnostic:** Use `apps/app/app/hooks/useAppAuth.ts` for components that work with either backend.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Start Vibecoding" icon="bolt" href="/getting-started/quickstart">
    Use AI to build features
  </Card>

  <Card title="Explore Components" icon="cube" href="/development/styling">
    See what's available
  </Card>

  <Card title="Understand Services" icon="plug" href="/development/mock-services">
    Learn about mock mode
  </Card>

  <Card title="Configure Backend" icon="database" href="/core-features/backend">
    Set up Supabase or Convex
  </Card>
</CardGroup>