Folder Structure

Complete guide to the AppLighter project structure. Understand the app screens, components, database, AI configuration, and key files layout.

Overview

AppLighter is a single Expo project with file-based routing, Vibecode DB for data, and deep Claude AI integration.

Root Structure

code/
├── app/                        # Expo Router pages (file-based routing)
├── components/                 # Reusable UI components
├── src/                        # Business logic (db, hooks, providers)
├── pocketbase/                 # PocketBase backend config
│   ├── command-scripts/        # DB push & seed scripts
│   └── pb_migrations/          # PocketBase migration files
├── supabase/                   # Supabase backend config
│   ├── migrations/             # Supabase SQL migrations
│   ├── seed/                   # Supabase seed data
│   └── types/                  # Generated Supabase types
├── .claude/                    # Claude AI configuration
│   ├── skills/                 # Domain-specific skill files
│   ├── commands/               # Slash commands
│   ├── agents/                 # AI agents
│   └── docs/                   # Architecture & API reference
├── .vscode/                    # VS Code settings
│   └── settings.json           # Editor configuration
├── theme.ts                    # Theme color tokens (light + dark)
├── theme.md                    # Theming documentation
├── global.css                  # Tailwind base styles
├── tailwind.config.js          # Tailwind/NativeWind config
├── metro.config.js             # Metro bundler config
├── babel.config.js             # Babel configuration
├── claude.md                   # Project context for AI
├── rapidnative.json            # RapidNative project config
├── .env                        # Environment variables
├── .env.example                # Environment template
├── app.json                    # Expo configuration
├── eas.json                    # EAS Build configuration
├── tsconfig.json               # TypeScript configuration
├── nativewind-env.d.ts         # NativeWind type declarations
└── package.json                # Dependencies

App Screens (app/)

The Expo Router pages with file-based routing.

app/
├── _layout.tsx                 # Root layout with auth state & providers
├── index.tsx                   # Entry point (redirect logic)
├── (auth)/                     # Public routes (guests)
│   ├── _layout.tsx             # Auth layout wrapper
│   ├── signin.tsx              # Sign in screen
│   └── signup.tsx              # Sign up screen
└── (app)/                      # Protected routes (authenticated)
    ├── _layout.tsx             # Tab navigation layout
    ├── home.tsx                # Home / Tasks screen
    └── profile.tsx             # User profile

Components (components/)

Reusable UI components with NativeWind styling.

components/
├── index.ts                    # Barrel exports
├── ThemeProvider.tsx            # Theme context provider
├── ThemeToggle.tsx              # Dark/light mode toggle
└── ThemedView.tsx              # Theme-aware container

Source Code (src/)

Business logic, database, hooks, and providers.

src/
├── db/
│   ├── client.ts               # Vibecode DB client (adapter selection)
│   ├── schema.ts               # TypeScript types (source of truth)
│   └── seeds/                  # Mock data for development
│       ├── index.ts            # Seed registry
│       ├── users.ts            # User mock data
│       ├── posts.ts            # Post mock data
│       └── stories.ts         # Story mock data
├── hooks/
│   ├── index.ts                # Hook exports
│   ├── useAuth.ts              # Authentication hook
│   └── useOffline.ts           # Offline detection
├── providers/
│   ├── AppProviders.tsx        # Root providers wrapper
│   └── ThemeProvider.tsx       # Theme provider
└── lib/
    └── queryClient.ts          # TanStack Query config

PocketBase (pocketbase/)

PocketBase backend configuration for schema management and data seeding.

pocketbase/
├── command-scripts/            # CLI scripts for PocketBase
│   ├── setup-collections.mjs  # Push schema collections (yarn pocketbase-db-push)
│   └── seed.mjs               # Seed data (yarn pocketbase-db-seed)
└── pb_migrations/              # PocketBase migration files

Scripts:

# Push schema collections to PocketBase
yarn pocketbase-db-push
 
# Seed data to PocketBase
yarn pocketbase-db-seed

Supabase (supabase/)

Supabase backend configuration for migrations and types.

supabase/
├── migrations/                 # SQL migration files
├── seed/                       # Seed data scripts
└── types/                      # Generated TypeScript types

Claude AI Configuration (.claude/)

Claude Code configuration for AI-assisted development.

.claude/
├── skills/                     # Domain-specific skill files (16 files)
│   ├── animations.md           # React Native Reanimated patterns
│   ├── expo-router.md          # File-based routing patterns
│   ├── gradients.md            # LinearGradient patterns
│   ├── images.md               # Image handling patterns
│   ├── lucide-icons.md         # Approved icons list & usage
│   ├── migrations.md           # Database migration patterns
│   ├── modal-patterns.md       # Modal component patterns
│   ├── nativewind-v4.md        # NativeWind styling guide
│   ├── react-native.md         # React Native best practices
│   ├── safe-area.md            # SafeAreaView patterns
│   ├── screen-layout.md        # Screen layout patterns
│   ├── tabs-navigation.md      # Tab navigation patterns
│   ├── tanstack-query.md       # Data fetching patterns
│   ├── theming.md              # Theme system guide
│   ├── typescript.md           # TypeScript patterns
│   └── vibecode.md             # Vibecode DB operations
├── commands/                   # Slash commands
│   ├── new-screen.md           # /new-screen - Generate screens
│   ├── new-component.md        # /new-component - Generate components
│   ├── new-table.md            # /new-table - Add database tables
│   ├── refactor.md             # /refactor - Refactoring guide
│   └── review.md               # /review - Code review checklist
├── agents/                     # AI agents
│   ├── code-reviewer.md        # Code review agent
│   ├── explorer.md             # Codebase exploration agent
│   └── refactor.md             # Refactoring agent
└── docs/                       # Reference documentation
    ├── architecture.md         # App architecture & data flow
    └── api-reference.md        # Hooks & import paths reference

Key Files

claude.md

Project context document that tells AI assistants about:

  • Tech stack and versions
  • File location conventions
  • Styling rules with NativeWind
  • Database patterns with Vibecode DB
  • Schema sync rules (schema.ts + seeds + registry)
  • Common mistakes to avoid

theme.ts

Theme color tokens defining light and dark mode:

  • Light Mode - Light purple tint background with Indigo-500 primary
  • Dark Mode - Deep indigo background with Indigo-400 primary
  • Semantic color tokens: background, foreground, card, primary, muted, border, destructive
  • Chart colors, sidebar colors, and font configuration (Inter + JetBrains Mono)

src/db/schema.ts

TypeScript types that serve as the source of truth for all database entities. The starter template includes three types: User, Post, and Story. When adding or updating tables, keep these three files in sync:

  1. src/db/schema.ts - TypeScript type definitions
  2. src/db/seeds/<table>.ts - Mock data
  3. src/db/seeds/index.ts - Seed registry

src/db/client.ts

Vibecode DB client that selects the adapter based on EXPO_PUBLIC_DB_ADAPTER:

  • mock (default) - In-memory with seeded data, auto-creates demo user
  • supabase - Cloud PostgreSQL via Supabase

Route Groups

The app uses Expo Router route groups:

GroupPathPurpose
(auth)/signin, /signupPublic routes for guests
(app)/home, /profileProtected routes requiring auth

Configuration Files

FilePurpose
package.jsonDependencies and scripts
app.jsonExpo app configuration
eas.jsonEAS Build configuration
tsconfig.jsonTypeScript configuration (strict mode)
tailwind.config.jsTailwind/NativeWind config
metro.config.jsMetro bundler configuration
babel.config.jsBabel configuration
global.cssTailwind base styles
theme.tsTheme color tokens (light + dark)
theme.mdTheming documentation
nativewind-env.d.tsNativeWind type declarations
.env.exampleEnvironment variable template
rapidnative.jsonRapidNative project configuration
.editorconfigEditor formatting rules
.prettierrcPrettier configuration
.eslintrc.jsESLint configuration
eslint.config.jsESLint flat config

Next Steps