> ## 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.

## 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:**

> [accordion] 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] 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] 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] 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] 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
> ```

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

> [card] For Vibecoders
>
> Start in `apps/app/app/` - build screens and components. Let AI help you!

> [card] For Explorers
>
> Browse `apps/app/app/components/` to see what's available, then check `apps/app/app/screens/` for screen examples.

## Finding What You Need

> [accordion] 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] 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] 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] 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] 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] 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.

## Next Steps

> [card] [Start Vibecoding](https://docs.shipnative.app/getting-started/quickstart.md)
>
> Use AI to build features

> [card] [Explore Components](https://docs.shipnative.app/development/styling.md)
>
> See what's available

> [card] [Understand Services](https://docs.shipnative.app/development/mock-services.md)
>
> Learn about mock mode

> [card] [Configure Backend](https://docs.shipnative.app/core-features/backend.md)
>
> Set up Supabase or Convex


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.