Project Structure

The VibeFast project is organized as a modern monorepo using Turborepo and PNPM, with clear separation between applications, packages, and shared utilities. This structure promotes modularity, scalability, and maintainability for large-scale applications.

Root Directory

The root of the monorepo contains configuration files, CI/CD workflows, and the main workspace directories.

• apps/: Contains all applications (currently the React Native app, structured for future web apps)
• packages/: Shared packages including backend logic and reusable UI components
• docs/: Project documentation and guides
• vf-agent/: AI Agent functionality and configurations
• turbo.json: Turborepo configuration for build orchestration
• pnpm-workspace.yaml: PNPM workspace configuration
• package.json: Root package.json with workspace scripts and dependencies

Applications

The apps directory contains the main application(s) in the monorepo.

• apps/native/: The React Native/Expo mobile application
  • src/: All frontend source code
  • assets/: Static assets like fonts, images, and Lottie animations
  • app.config.ts: Expo configuration
  • package.json: Native app dependencies and scripts

Packages

The packages directory contains shared packages that can be used across applications.

• packages/backend/ (@vibefast/backend): Convex backend as a separate package
  • convex/: All backend code including schema, functions, and auth configuration
  • index.ts: Backend package exports and client setup
• packages/ui/: Shared UI components library
  • components/: Reusable UI components across applications
  • index.ts: UI package exports

Frontend Structure

The native app source code is organized using a feature-sliced architecture with enhanced modularity.

• app/: Routing & Screens. File-based routing with Expo Router, containing all screens and navigation layouts
• components/: Reusable UI. Core UI components organized by category (ui, advanced-ui, demo, etc.)
• features/: Business Logic. Feature modules with complete functionality (except for essential ones, they removed and added using our CLI):
  • authentication/: Auth flows and UI
  • chatbot/: AI chatbot with advanced capabilities
  • voice-bot/: Voice interaction system
  • wake-word/: Hotword detection
  • audio-recorder/: Audio capture and processing
  • image-analyzer/, image-generator/: AI-powered image features
  • payments/: Payment processing and subscriptions
  • charts/: Data visualization components
  • quick-actions/: Contextual shortcut system
  • quiz/: Interactive quiz functionality
  • tracker-app/: Simple calorie tracker with a clean UI (extra, nice-to-have feature)
• core/: Core Services. Application-wide services (auth, analytics, cache, payments, storage)
• lib/: Shared Utilities. Hooks, i18n, state management, and shared helpers
• providers/: React Providers. Context providers for Convex, theme, analytics, etc.
• api-client/: API Layer. Type-safe API clients for backend services

Backend Structure

The backend package contains all Convex-related backend functionality.

• schema.ts: Database schema definitions and relationships
• auth.ts & auth.config.ts: Authentication configuration using @convex-dev/auth
• http.ts & router.ts: HTTP endpoints and routing configuration
• agents.ts: AI agent configurations and management
• tools/: Advanced AI tools (knowledge retrieval, search, user profiles)
• chatbotAgent.ts: Enhanced chatbot with agent capabilities
• ragKnowledge.ts: Retrieval-Augmented Generation knowledge base
• Feature modules: Individual backend functions organized by domain (auth, payments, images, etc.)

Development Scripts

The monorepo uses Turborepo for efficient build orchestration. Key scripts include:

{
  "dev": "turbo dev", // this runs your app, web and the backend
  "dev:native": "turbo -F native dev",
  "dev:web": "turbo -F web dev",
  "dev:server": "turbo -F @vibefast/backend dev",
  "build": "turbo build",
  "build:backend": "turbo -F @vibefast/backend build",
  "test": "turbo test",
}

Environment Management

The monorepo supports multiple environments:

• Local: Development environment with debug features
• Staging: Pre-production testing environment
• Production: Live deployment environment

Environment-specific builds are configured through Expo EAS profiles and environment variables.