Folder Structure

Complete guide to the AppLighter monorepo structure.

Overview

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

Root Structure

applighter/
├── apps/                    # Application packages
│   ├── mobile/              # Expo React Native app
│   └── server/              # Hono API backend
├── packages/                # Shared libraries
│   ├── client/              # Core Vibecode DB client
│   ├── sqlite-core/         # SQLite utilities
│   ├── sqlite-expo/         # Expo SQLite driver
│   ├── sqlite-web/          # Web SQLite (sql.js)
│   ├── adapter-sqlite/      # SQLite adapter alias
│   ├── adapter-supabase/    # Supabase adapter alias
│   ├── adapter-custom/      # Custom adapter alias
│   ├── adapter-vibecode/    # Vibecode adapter alias
│   └── vibecode-db/         # Master package
├── .claude/                 # Claude AI configuration
│   └── commands/            # AI generation commands
├── claude.md                # Project context for AI
├── PLAN.md                  # Architecture decisions & templates
├── SCRATCHPAD.md            # Working notes
├── package.json             # Root workspace config
├── pnpm-workspace.yaml      # pnpm workspaces
└── 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)
│   ├── (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
│       ├── create-post.tsx  # Create content screen
│       ├── profile.tsx      # User 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        # Vibecode DB 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
│
├── assets/                  # Static assets
│   ├── icon.png             # App icon
│   ├── splash.png           # Splash screen
│   └── adaptive-icon.png    # Android adaptive icon
│
├── Configuration
│   ├── app.json             # Expo 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
│   ├── .env                 # Environment variables
│   └── .env.example         # Example env file
│
└── theme.ts                 # Theme CSS variables

Server (apps/server/)

The Hono REST API backend.

apps/server/
├── src/
│   ├── index.ts             # Server entry point
│   ├── db/
│   │   ├── schema.ts        # Database schema
│   │   └── store.ts         # Database store
│   ├── 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.

packages/client

Core Vibecode DB client with query builder and adapters.

packages/client/
├── src/
│   ├── client/
│   │   ├── createClient.ts  # Client factory
│   │   └── queryBuilder.ts  # Query builder
│   ├── schema/
│   │   ├── schema.ts        # Schema helpers
│   │   ├── table.ts         # Table definitions
│   │   └── columns.ts       # Column types
│   ├── auth/
│   │   ├── authClient.ts    # Auth implementation
│   │   └── types.ts         # Auth types
│   ├── adapters/
│   │   ├── supabase/        # Supabase adapter
│   │   ├── custom/          # Custom REST adapter
│   │   └── vibecode/        # Vibecode adapter
│   └── ddl/
│       └── generateDDL.ts   # SQL generation
└── package.json

packages/sqlite-core

SQLite utilities and base adapter.

packages/sqlite-core/
├── src/
│   ├── sqlite/
│   │   ├── base-adapter.ts  # Base SQLite adapter
│   │   ├── executor.ts      # Query executor
│   │   └── driver.ts        # Driver interface
│   ├── sql-utils/
│   │   ├── buildSelect.ts   # SELECT builder
│   │   ├── buildInsert.ts   # INSERT builder
│   │   ├── buildUpdate.ts   # UPDATE builder
│   │   ├── buildDelete.ts   # DELETE builder
│   │   └── buildWhere.ts    # WHERE clause
│   └── auth/
│       └── sqlite-auth-executor.ts
└── package.json

packages/sqlite-expo

Expo SQLite driver for React Native.

packages/sqlite-expo/
├── src/
│   └── sqlexpo-driver.ts    # Expo SQLite driver
└── package.json

packages/sqlite-web

Web SQLite using sql.js (WASM).

packages/sqlite-web/
├── src/
│   └── sqljs-driver.ts      # sql.js driver
└── package.json

Claude Configuration (.claude/)

AI assistant configuration for code generation.

.claude/
├── 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
└── settings.local.json      # Local settings

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

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 | | pnpm-workspace.yaml | Defines apps/* and packages/* | | 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 | |-------|------|---------| | (auth) | /signin, /signup | Public routes for guests | | (app) | /home, /profile | Protected routes requiring auth |

Next Steps