Project Structure

Understanding the folder organization and file conventions used in PHL RN Boilerplate.

Complete Structure

typescript
phl-rn-boilerplate/
├── src/
│   ├── app/                    # 📱 Expo Router (File-based routing)
│   │   ├── _layout.tsx         # Root layout with providers
│   │   └── (tabs)/             # Tab navigator group
│   │       ├── _layout.tsx     # Tabs configuration
│   │       ├── index.tsx       # Home screen
│   │       ├── arch.tsx        # Architecture demo
│   │       └── settings.tsx    # Settings screen
│   │
│   ├── components/             # 🧩 Reusable UI Components
│   │   ├── ui/                 # Base UI components
│   │   │   ├── Button.tsx
│   │   │   ├── Card.tsx
│   │   │   ├── Input.tsx
│   │   │   ├── Text.tsx
│   │   │   ├── ThemeToggle.tsx
│   │   │   └── FloatingTabBar.tsx
│   │   ├── dev/                # Development tools
│   │   │   └── DebugFAB.tsx
│   │   └── index.ts
│   │
│   ├── core/                   # ⚙️ Core Configuration
│   │   └── config/
│   │       ├── bootstrap.ts    # App initialization
│   │       ├── env.ts          # Environment variables
│   │       └── index.ts
│   │
│   ├── data/                   # 💾 Data Layer
│   │   ├── api/                # HTTP clients
│   │   │   ├── client.ts       # Axios instance
│   │   │   └── endpoints/      # API endpoints
│   │   └── storage/            # Local storage
│   │       ├── mmkv.ts         # MMKV instance
│   │       └── index.ts
│   │
│   ├── domain/                 # 🎯 Domain Layer
│   │   ├── entities/           # Type definitions
│   │   │   └── user.ts
│   │   └── schemas/            # Zod validation schemas
│   │       └── user.schema.ts
│   │
│   ├── hooks/                  # 🪝 Custom React Hooks
│   │   ├── useApi.ts
│   │   ├── useForm.ts
│   │   └── index.ts
│   │
│   ├── i18n/                   # 🌍 Internationalization
│   │   ├── index.ts            # i18next setup
│   │   └── locales/
│   │       ├── pt-BR.ts
│   │       └── en-US.ts
│   │
│   ├── presentation/           # 🎨 Presentation Layer (MVVM)
│   │   ├── screens/            # Screen components (Views)
│   │   │   ├── HomeScreen.tsx
│   │   │   ├── ArchScreen.tsx
│   │   │   ├── SettingsScreen.tsx
│   │   │   └── index.ts
│   │   └── viewmodels/         # Presentation logic
│   │       ├── useHomeViewModel.ts
│   │       ├── useArchViewModel.ts
│   │       ├── useSettingsViewModel.ts
│   │       └── index.ts
│   │
│   ├── providers/              # 🔌 Context Providers
│   │   ├── AppProvider.tsx     # Root provider
│   │   ├── ThemeProvider.tsx   # Theme management
│   │   ├── query-client.ts     # React Query setup
│   │   └── index.ts
│   │
│   ├── stores/                 # 🗄️ Global State (Zustand)
│   │   ├── app.store.ts        # App-wide state
│   │   └── index.ts
│   │
│   ├── styles/                 # 🎨 Global Styles
│   │   └── global.css          # NativeWind styles
│   │
│   └── types/                  # 📝 TypeScript Types
│       └── global.d.ts
│
├── assets/                     # 🖼️ Static Assets
│   ├── images/
│   ├── fonts/
│   └── hero-image.png
│
├── .env.example                # Environment template
├── .gitignore
├── app.json                    # Expo configuration
├── babel.config.js             # Babel configuration
├── metro.config.js             # Metro bundler config
├── package.json                # Dependencies
├── README.md                   # Project documentation
├── tailwind.config.js          # NativeWind config
└── tsconfig.json               # TypeScript config

Key Folders Explained

📱

src/app/

Expo Router pages. Each file becomes a route. Supports nested layouts, groups, and dynamic routes.

index.tsx → /
(tabs)/settings.tsx → /settings
user/[id].tsx → /user/:id
🎨

src/presentation/

MVVM presentation layer. Contains screens (Views) and their corresponding ViewModels (hooks) that manage UI logic and state.

screens/ - UI components
viewmodels/ - Presentation logic
🎯

src/domain/

Business logic and domain models. Entities define your data structures, schemas provide validation.

entities/ - TypeScript interfaces
schemas/ - Zod validation
💾

src/data/

Data access layer. API clients for remote data, storage for local persistence.

api/ - HTTP requests (Axios)
storage/ - MMKV persistence
🗄️

src/stores/

Global state management. Zustand stores with MMKV persistence for app-wide state (theme, language, auth, etc.).

Uses Zustand + MMKV for fast, persistent state
🧩

src/components/

Reusable UI components. Shared components that can be used across multiple screens.

ui/ - Base components (Button, Card, etc.)
dev/ - Development tools
🌍

src/i18n/

Internationalization. Translations for multiple languages using i18next.

Includes Portuguese (pt-BR) and English (en-US) by default

Naming Conventions

Files

  • Components: PascalCase - Button.tsx, UserCard.tsx
  • Hooks: camelCase with "use" prefix - useAuth.ts, useApi.ts
  • Stores: camelCase with ".store" suffix - app.store.ts
  • ViewModels: camelCase with "use" prefix - useHomeViewModel.ts
  • Screens: PascalCase with "Screen" suffix - HomeScreen.tsx
  • Types: PascalCase - User, Post

Folders

  • Lowercase: components, hooks, stores
  • Singular: Prefer singular names - component not components (except when convention dictates)

Import Paths

The project uses TypeScript path aliases for cleaner imports:

typescript
// ✅ Good - Using path alias
import { Button } from '@/components/ui/Button';
import { useAppStore } from '@/stores/app.store';
import { User } from '@/domain/entities/user';

// ❌ Bad - Relative paths
import { Button } from '../../../components/ui/Button';
import { useAppStore } from '../../stores/app.store';
Path aliases are configured in tsconfig.json with @/ mapping to src/.

Index Files

Each major folder contains an index.ts file for clean exports:

src/components/ui/index.ts
export { Button } from './Button';
export { Card } from './Card';
export { Input } from './Input';
export { Text } from './Text';

This allows importing multiple components in one line:

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

File Organization Best Practices

✅ Co-locate related files

Keep ViewModels close to their Views, schemas near their entities.

✅ One component per file

Each component should have its own file for better maintainability.

✅ Use index files

Export multiple items from a folder using index.ts files.

✅ Group by feature

For larger apps, consider organizing by feature instead of by type.

Next Steps

Learn the Architecture →

Understand how MVVM structures your code.