Mobile Folder Structure

Mobile Folder Structure

The merq-mobile codebase is organized into two main areas: a core/ directory for shared infrastructure and a features/ directory that contains self-contained modules. This structure is designed to support the offline-first architecture and promote code reuse.

High-Level Structure

• Directorysrc/ - The main application source code.

  • Directorycore/ - Shared code, services, and hooks used by all features.

    • …
  • Directoryfeatures/ - Individual feature modules, each with its own screens, components, and hooks.

    • …
• Directoryandroid/ - Android-specific native code and configuration.

  • …
• Directoryios/ - iOS-specific native code and configuration.

  • …
• index.js - The entry point of the React Native application.
• package.json - Project metadata and dependencies.

The src/ Directory in Detail

All JavaScript/TypeScript code for the application lives inside src/.

core/

• Purpose: Provides the foundational building blocks for the entire application. Code in core is generic and can be used by any feature.
• Subdirectories:
  • atoms/: Contains global client-side state definitions using Jotai. This is used for state that needs to be shared across the entire app, such as authentication status (authAtom) and the current user profile (profileAtom).
  • hooks/: Shared custom React hooks that are not tied to a specific feature (e.g., useAuth, usePermissions).
  • services/: Contains the configured Axios instance (apiClient.ts) and base API service functions.
  • storage/: Provides helper functions for interacting with MMKV, the mandatory local storage solution. This is the only place where MMKV should be directly accessed.
  • theme/: Defines the application-wide theme for React Native Paper (MD3), including colors, fonts, and component styles.
  • types/: Contains shared TypeScript types and interfaces used across multiple features.

features/

• Purpose: Contains self-contained feature modules. Each folder inside features/ represents a distinct part of the application (e.g., outlets, visits, login).
• Structure of a Feature Module (e.g., features/outlets/):
  • screens/: The main components for each screen in the feature (e.g., OutletListScreen.tsx, OutletDetailScreen.tsx).
  • components/: Reusable components that are specific to this feature (e.g., OutletCard.tsx).
  • hooks/: Feature-specific hooks, including all TanStack Query hooks for fetching the feature’s data (e.g., useOutletsQuery.ts). These hooks are responsible for defining the queryKey, the queryFn, and setting networkMode: 'offlineFirst'.
  • types.ts: TypeScript interfaces specific to this feature.
  • navigation.tsx: (Optional) If the feature has its own stack of screens, the React Navigation stack navigator is defined here.
  • index.ts: A mandatory barrel file that exports all the public components, hooks, and types from the feature. This allows for clean imports from other parts of the app (e.g., import { OutletCard } from '@features/outlets').

Convention: Path Aliases

The project uses path aliases in tsconfig.json to simplify imports:

• @core/* maps to src/core/*
• @features/* maps to src/features/*

This avoids long relative paths (../../../) and makes the code easier to read and refactor.