Project Structure

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

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:

app/components/ - UI Components

Pre-built components like Button, Card, TextField, etc. Use these instead of building from scratch.

import { Button, Card, Text } from '@/components'

app/hooks/ - Auth Hooks

Native auth hooks for each backend, plus a unified hook.

// 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'

app/stores/ - Global State

Zustand stores for app-wide state like subscriptions and preferences.

import { useSubscriptionStore } from '@/stores/subscriptionStore'

const { isPro, checkEntitlement } = useSubscriptionStore()

app/services/ - External APIs

Service clients for Supabase, RevenueCat, PostHog, etc. Automatically uses mocks when API keys are missing.

import { supabase } from '@/services/supabase'

app/theme/ - Design System

Unistyles theme with colors, spacing, typography. Always use theme values instead of hardcoding.

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

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:

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

For Vibecoders

Start in apps/app/app/ - build screens and components. Let AI help you!

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

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

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.

// In ProfileCard.tsx
export const ProfileCard = () => { ... }

// In index.ts
export * from "./ProfileCard"

Where do I add global state?

Create a Zustand store in apps/app/app/stores/. Follow the pattern in existing stores like subscriptionStore.ts.

Where do I customize the theme?

Edit apps/app/app/theme/unistyles.ts. This file defines colors, spacing, typography, shadows, and all design tokens.

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.

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

Start Vibecoding

Use AI to build features

Explore Components

See what’s available

Understand Services

Learn about mock mode

Configure Backend

Set up Supabase or Convex

Introduction

Getting Started

Core Features

Development

Deployment

Support

What You Cloned

The Two Main Apps

Mobile App (`apps/app/`)

Convex Backend (`convex/`)

Marketing Page (`apps/web/`)

Documentation Files

The AI Documentation System (Layered Context)

1. Discovery Layer (`AGENTS.md`)

2. Specification Layer (`vibe/` folders)

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

Configuration Files

Root Level

App Level (`apps/app/`)

Convex Level (`convex/`)

How the Monorepo Works

Where to Start

For Vibecoders

For Explorers

Finding What You Need

Next Steps

Start Vibecoding

Explore Components

Understand Services

Configure Backend

​What You Cloned

​The Two Main Apps

​Mobile App (apps/app/)

​Convex Backend (convex/)

​Marketing Page (apps/web/)

​Documentation Files

​The AI Documentation System (Layered Context)

​1. Discovery Layer (AGENTS.md)

​2. Specification Layer (vibe/ folders)

​3. Tech Stack Rules (in AGENTS.md)

​Configuration Files

​Root Level

​App Level (apps/app/)

​Convex Level (convex/)

​How the Monorepo Works

​Where to Start

For Vibecoders

For Explorers

​Finding What You Need

​Next Steps

Start Vibecoding

Explore Components

Understand Services

Configure Backend

What You Cloned

The Two Main Apps

Mobile App (`apps/app/`)

Convex Backend (`convex/`)

Marketing Page (`apps/web/`)

Documentation Files

The AI Documentation System (Layered Context)

1. Discovery Layer (`AGENTS.md`)

2. Specification Layer (`vibe/` folders)

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

Configuration Files

Root Level

App Level (`apps/app/`)

Convex Level (`convex/`)

How the Monorepo Works

Where to Start

Finding What You Need

Next Steps