Folder Structure

Complete guide to the AppLighter monorepo structure. Understand the mobile app, API server, shared packages, AI configuration, and key files layout.

Overview

AppLighter is a Turbo-powered monorepo with two main applications and shared packages for database abstraction.

Root Structure

code/
├── apps/                    # Application packages
│   ├── mobile/              # Expo React Native app
│   └── api/                 # API backend
├── packages/                # Shared libraries
├── .ai/                     # AI assistant configuration
├── .claude/                 # Claude AI configuration
│   ├── PLAN.md              # Architecture decisions & templates
│   ├── commands/            # AI generation commands
│   └── docs/                # AI reference docs
├── scripts/                 # Build & utility scripts
├── claude.md                # Project context for AI
├── SCRATCHPAD.md            # Working notes
├── package.json             # Root workspace config
├── yarn.lock                # Yarn lockfile
└── turbo.json               # Turbo build config

Mobile App (apps/mobile/)

The Expo React Native application with file-based routing.

apps/mobile/
├── app/                     # Expo Router pages (file-based routing)
│   ├── _layout.tsx          # Root layout with auth state
│   ├── index.tsx            # Entry point (redirect logic)
│   ├── (onboarding)/        # Onboarding flow (first-time users)
│   │   ├── _layout.tsx      # Onboarding layout wrapper
│   │   ├── splash.tsx       # Splash / welcome screen
│   │   ├── login.tsx        # Login screen
│   │   ├── signup.tsx       # Sign up screen (onboarding variant)
│   │   ├── otp.tsx          # OTP verification screen
│   │   ├── profile-setup.tsx # Profile setup screen
│   │   └── forgot-password.tsx # Password reset screen
│   ├── (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      # App layout with tab navigation
│       ├── home.tsx         # Home/feed screen
│       ├── my-courses.tsx   # User's enrolled courses
│       ├── course-detail.tsx # Course detail & lessons
│       ├── lesson-player.tsx # Video/content player
│       ├── progress.tsx     # Learning progress tracker
│       ├── create-post.tsx  # Create content screen
│       ├── profile.tsx      # User profile screen
│       ├── edit-profile.tsx # Edit profile screen
│       └── storage.tsx      # File storage screen
│
├── components/              # Reusable UI components
│   ├── index.ts             # Barrel export
│   ├── ui/                  # gluestack-ui v3 components
│   │   ├── box/             # Layout container
│   │   ├── button/          # Action buttons
│   │   ├── input/           # Form inputs
│   │   ├── text/            # Typography
│   │   └── ...              # Other UI primitives
│   ├── PostCard.tsx         # Post display component
│   ├── PostCardSkeleton.tsx # Loading skeleton
│   ├── ThemedView.tsx       # Theme-aware container
│   ├── ThemeProvider.tsx    # Theme context
│   └── ThemeToggle.tsx      # Dark/light toggle
│
├── src/                     # Business logic
│   ├── db/
│   │   ├── client.ts        # Supabase client initialization
│   │   └── schema.ts        # Table schemas & types
│   ├── hooks/
│   │   ├── index.ts         # Hook exports
│   │   ├── useAuth.ts       # Authentication hook
│   │   └── useOffline.ts    # Offline detection
│   ├── lib/
│   │   └── queryClient.ts   # TanStack Query config
│   └── providers/
│       ├── AppProviders.tsx  # Root providers
│       └── ThemeProvider.tsx # Theme provider
│
├── lib/                     # Utilities and helpers
│   └── icons.ts             # Icon mappings
│
├── assets/                  # Static assets
│   ├── icon.png             # App icon
│   ├── splash.png           # Splash screen
│   ├── adaptive-icon.png    # Android adaptive icon
│   └── images/              # Image assets
│       ├── backgrounds/     # Background images
│       ├── cards/           # Card images
│       ├── hero/            # Hero images
│       └── profiles/        # Profile images
│
├── supabase/                # Supabase local config
│   ├── config.toml          # Supabase project config
│   └── migrations/          # Database migrations
│
├── Configuration
│   ├── app.json             # Expo configuration
│   ├── eas.json             # EAS Build configuration
│   ├── package.json         # Dependencies
│   ├── tsconfig.json        # TypeScript config
│   ├── tailwind.config.js   # Tailwind/NativeWind config
│   ├── metro.config.js      # Metro bundler config
│   ├── babel.config.js      # Babel configuration
│   ├── global.css           # Global CSS styles
│   ├── .env                 # Environment variables
│   └── .env.example         # Example env file
│
└── theme.ts                 # Theme CSS variables

API (apps/api/)

The REST API backend.

apps/api/
├── src/
│   ├── index.ts             # Server entry point
│   ├── db/
│   │   ├── client.ts        # Database client setup
│   │   └── schema.ts        # Database schema
│   ├── middleware/
│   │   └── auth.ts          # JWT authentication
│   └── routes/
│       ├── auth.ts          # Auth endpoints
│       ├── db.ts            # Database proxy
│       ├── posts.ts         # Posts CRUD
│       ├── profiles.ts      # User profiles
│       └── storage.ts       # File storage
│
├── package.json             # Server dependencies
├── tsconfig.json            # TypeScript config
└── .env.example             # Environment template

Packages

Shared libraries that both apps can use.

Supabase (@supabase/supabase-js)

The project uses the official Supabase JavaScript client for database queries, authentication, storage, and realtime subscriptions. The client is initialized in src/db/client.ts and provides:

  • Database - Query builder for PostgreSQL tables
  • Auth - User authentication (email, social login, magic links)
  • Storage - File uploads and management
  • Realtime - Live subscriptions to database changes

AI Configuration (.ai/)

Shared AI assistant configuration used across editors.

.ai/
├── .claude/                 # Claude-specific config
├── .cursor/                 # Cursor-specific config
├── commands/                # Custom AI commands
│   ├── new-screen.md        # Generate screens
│   ├── new-component.md     # Generate components
│   ├── new-table.md         # Generate tables
│   ├── refactor.md          # Refactoring guide
│   └── review.md            # Code review checklist
├── docs/                    # AI reference documentation
│   ├── reference.md         # API & pattern reference
│   ├── rules.md             # Coding rules & conventions
│   └── templates.md         # Code templates
├── base.md                  # Base AI instructions
├── project.md               # Project-specific context
└── scratchpad-template.md   # Scratchpad template

Claude Configuration (.claude/)

Claude Code configuration for AI-assisted development.

.claude/
├── PLAN.md                  # Architecture decisions & templates
├── commands/                # Custom Claude commands
│   ├── new-screen.md        # Generate screens
│   ├── new-component.md     # Generate components
│   ├── new-table.md         # Generate tables
│   ├── refactor.md          # Refactoring guide
│   └── review.md            # Code review checklist
└── docs/                    # AI reference documentation
    ├── reference.md         # API & pattern reference
    ├── rules.md             # Coding rules & conventions
    └── templates.md         # Code templates

Key Files

claude.md

Project context document that tells AI assistants about:

  • Tech stack and versions
  • Architecture rules
  • File location conventions
  • Styling rules with NativeWind
  • Data patterns with TanStack Query
  • Auth patterns
  • Common mistakes to avoid

.claude/PLAN.md

Architecture documentation containing:

  • Project overview
  • Architecture decisions with tradeoffs
  • Data flow diagrams
  • Auth flow diagrams
  • Code templates (screens, components, hooks, tables)
  • Database operations examples
  • Theme variable reference

SCRATCHPAD.md

Working memory file for:

  • Current focus notes
  • Debug findings
  • Ideas for later
  • Temporary notes during development

Configuration Files

| File | Purpose | | -------------------- | ------------------------------------------ | | package.json | Root workspace with Turbo scripts | | turbo.json | Build caching and task orchestration | | tsconfig.base.json | Shared TypeScript settings |

Route Groups

The mobile app uses Expo Router route groups:

| Group | Path | Purpose | | -------------- | ---------------------------------------------------------------------------- | -------------------------------------- | | (onboarding) | /splash, /login, /signup, /otp, /profile-setup, /forgot-password | First-time user onboarding flow | | (auth) | /signin, /signup | Public routes for returning guests | | (app) | /home, /my-courses, /course-detail, /lesson-player, /progress, /profile, /edit-profile, /create-post, /storage | Protected routes requiring auth |

Next Steps