Project structure

NativeExpress keeps routes in src/app/, each AI feature in src/features/, shared app code in src/, and the database and edge functions in supabase/.

• src
  • app - Screens (file-based routing)
    • (public) - Unauthenticated screens
    • (protected) - Authenticated screens
    • auth - confirmed.tsx, the email-link landing route
    • index.tsx - Entry route (onboarding / welcome / home)
    • update-password.tsx - Recovery-link screen, any auth state
    • _layout.tsx - Root layout, fonts, providers
  • assets - Icons and images
  • features - Chat, Create and Scan, each removable
    • index.ts - The feature registry Home and the tab layout read
    • types.ts - The Feature interface
    • chat - feature.ts, screens, components/, hooks/, repository.ts, chatTransport.ts
    • create - feature.ts, screen, components/, hooks/, repository.ts, generateImage.ts
    • scan - feature.ts, screen, components/, hooks/, repository.ts
    • README.md - How to remove or add a feature
  • components - Shared UI
  • hooks - Shared business logic (React Query)
  • i18n - Translations (en, de)
  • lib - Shared libraries
    • db
    • storage - chat-media upload, signed URLs, image picking
    • format
    • schema
    • supabase.ts - Supabase client
    • secure-storage.ts - Keychain / Keystore session storage
    • edgeFunction.ts - Typed edge-function calls and error codes
    • logger.ts - logError, reporting through the crash-reporting port
  • provider - Global context providers (session, RevenueCat, paywall, analytics, theme)
  • services - Swappable integrations (ports pattern)
    • analytics - Port, PostHog adapter, typed events
    • crash-reporting - Port, Sentry adapter, no-op
    • paywall - Port, RevenueCat and Superwall adapters
    • push.ts - OneSignal
  • theme - Generated themes and their seeds
    • seeds - mono.json, paper.json, slate.json
    • themes - mono.css, generated from its seed
    • index.ts - APP_THEME + setAppTheme()
  • __tests__/app - Route screen tests, mirroring src/app (a test under app/ would ship as a route)
  • global.css - Tailwind v4 / Uniwind CSS entry, the theme import, font variables
  • env.d.ts - Ambient type references (expo, uniwind)
• supabase
  • functions - Edge Functions (Deno)
  • migrations - One initial schema migration, with a marked SQL block per feature
  • config.toml - Local Supabase config
• scripts - CI checks, the removal scripts, and theme/ for the design pipeline
• credentials - Gitignored: the App Store Connect key, asc.env and the Play service account
• .maestro - End-to-end flows
• .claude/skills - Setup, design, development and shipping skills
• .agents/skills - Setup, design and development skill copies
• .env.example - Client environment variables
• PRODUCT.md - The product brief
• config.js - App identity, integrations and AI config import
• app.config.js - Expo app configuration
• eas.json - EAS build and submit profiles
• store.config.json - App Store listing metadata
• metro.config.js - Metro + Uniwind configuration
• uniwind-types.d.ts - Generated Uniwind types
• DESIGN.md - Design language reference
• AGENTS.md - Instructions for coding agents

The files you’ll touch first

• PRODUCT.md - What the app is, what it keeps, how it should look
• config.js - App name, identifiers, EAS project and Google OAuth IDs
• .env.example - Copy to .env.local for client configuration
• src/theme/seeds/<name>.json - Your theme's colours; yarn theme:generate renders it
• src/global.css - Fonts, breakpoints and Tailwind entry point
• supabase/functions/chat/config.json - The chat models; generate/ and identify/ have their own
• supabase/functions/_utils/ai.config.json - Free allowance and AI consent version
• DESIGN.md - Design conventions for new screens

The app and the edge functions read the same AI configuration files. After changing one, follow the redeploy steps in Models so both use the same values.

Where to add code

Put route files in src/app/, shared UI in src/components/, and shared data-fetching hooks in src/hooks/. A feature’s own screens, components, hooks and queries belong under src/features/<name>/, with its Supabase queries in that feature’s repository.ts. Features never import one another; yarn check:features rejects it. Vendor integrations are wrapped by src/services/; screens use those wrappers.

Keep route tests under src/__tests__/app/ and components out of src/app/, because every file inside it becomes a route; yarn check:routes fails on a file there that has no default export. See testing and the conventions skill before adding a new feature, and Removing features and integrations for taking one out.