🏗️ Shipnative Project Structure

Shipnative is a monorepo - a single repository containing multiple apps and shared packages. This guide explains how the codebase is organized so you can navigate and extend your project effectively.

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/                     # Landing page (Next.js)
│
├── packages/                    # Shared code between apps
│
├── vibe/                        # AI context files for vibecoding
│   ├── SERVICES.md             # Service architecture overview
│   └── MOCK_SERVICES.md        # How mock mode works
│
├── *.md                         # Developer documentation
│   ├── README.md               # Main readme
│   ├── SUPABASE.md            # Auth & database setup
│   ├── MONETIZATION.md        # Payments setup
│   ├── ANALYTICS.md           # Analytics setup
│   └── ...                     # More feature guides
│
├── 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
│   ├── utils/                  # Helper functions
│   ├── theme/                  # Design system
│   │   └── unistyles.ts        # Theme configuration
│   ├── config/                 # App configuration
│   └── 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/stores/ - Global State

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

import { useAuthStore } from '@/stores/authStore'

const { user, signIn, signOut } = useAuthStore()

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

🌐 Landing Page (`apps/web/`)

A Next.js application for your app’s marketing website.

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

🤖 AI Context Files (Two Vibe Folders)

Shipnative has two vibe folders with different purposes:

`apps/app/vibe/` - App-Specific Context

These files teach AI about your app’s specific implementation:

CONTEXT.md - App features, architecture, current state
TECH_STACK.md - Technologies used and decisions made
STYLE_GUIDE.md - Code patterns and conventions
ARCHITECTURE.md - App architecture details
SCREEN_TEMPLATES.md - Screen implementation patterns

`vibe/` (Root) - Project-Wide Context

These files cover project-wide infrastructure:

SERVICES.md - Overview of all external services (Supabase, RevenueCat, PostHog, Sentry)
MOCK_SERVICES.md - How mock mode works, customization guide, and mock data seeding

When you use the “golden prompt”, AI assistants read both folders along with .cursorrules to understand your project structure and generate appropriate code.

🔧 Configuration Files

Root Level

package.json - Monorepo dependencies and scripts
turbo.json - Turborepo build configuration
tsconfig.json - TypeScript configuration
.cursorrules - Rules for AI code assistants

App Level (`apps/app/`)

app.json - Expo configuration (app name, bundle ID, etc.)
.env - Environment variables (API keys)
package.json - App-specific dependencies
tsconfig.json - TypeScript 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

📦 Packages (Shared Code)

The packages/ folder contains shared utilities that both apps can use. As you build, you might add shared types, utilities, or components here.

packages/
└── (shared packages - currently minimal)

🎯 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/(tabs)/ 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 authStore.ts or 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 modify API calls?

Check apps/app/app/services/ for service clients. Each service has its own file (e.g., supabase.ts, revenuecat.ts, posthog.ts).

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 real services

Introduction

🚀 Getting Started

🌟 Core Features

🧑‍💻 Development

🚀 Deployment

Support

Project Structure

🏗️ Shipnative Project Structure

What You Cloned

The Two Main Apps

📱 Mobile App (`apps/app/`)

🌐 Landing Page (`apps/web/`)

📄 Documentation Files

🤖 AI Context Files (Two Vibe Folders)

`apps/app/vibe/` - App-Specific Context

`vibe/` (Root) - Project-Wide Context

🔧 Configuration Files

Root Level

App Level (`apps/app/`)

🔄 How the Monorepo Works

📦 Packages (Shared Code)

🎯 Where to Start

For Vibecoders

For Explorers

🔍 Finding What You Need

Next Steps

Start Vibecoding

Explore Components

Understand Services

Configure Backend

Introduction

🚀 Getting Started

🌟 Core Features

🧑‍💻 Development

🚀 Deployment

Support

​🏗️ Shipnative Project Structure

​What You Cloned

​The Two Main Apps

​📱 Mobile App (apps/app/)

​🌐 Landing Page (apps/web/)

​📄 Documentation Files

​🤖 AI Context Files (Two Vibe Folders)

​apps/app/vibe/ - App-Specific Context

​vibe/ (Root) - Project-Wide Context

​🔧 Configuration Files

​Root Level

​App Level (apps/app/)

​🔄 How the Monorepo Works

​📦 Packages (Shared Code)

​🎯 Where to Start

For Vibecoders

For Explorers

​🔍 Finding What You Need

​Next Steps

Start Vibecoding

Explore Components

Understand Services

Configure Backend

🏗️ Shipnative Project Structure

What You Cloned

The Two Main Apps

📱 Mobile App (`apps/app/`)

🌐 Landing Page (`apps/web/`)

📄 Documentation Files

🤖 AI Context Files (Two Vibe Folders)

`apps/app/vibe/` - App-Specific Context

`vibe/` (Root) - Project-Wide Context

🔧 Configuration Files

Root Level

App Level (`apps/app/`)

🔄 How the Monorepo Works

📦 Packages (Shared Code)

🎯 Where to Start

🔍 Finding What You Need

Next Steps