Project Structure

Complete guide to the PokéDex Fleek codebase organization and architecture

Overview

PokéDex Fleek follows a feature-based architecture that separates concerns and makes the codebase scalable and maintainable. The project is built with React Native and Expo, using modern patterns for code organization.

Directory Tree

pokedex-fleek/
├── assets/                    # Static resources
│   ├── img/                   # Images and logos
│   │   ├── home_background.png
│   │   └── pokedex_logo.png
│   ├── sounds/                # Audio files
│   │   ├── intro_theme.mp3
│   │   └── route1_loop.mp3
│   ├── icon_pokedex.png       # App icon
│   ├── adaptive-icon-pokedex.png
│   └── splash-icon-pokedex.png
│
├── src/                       # Source code
│   ├── features/              # Feature modules (domain logic)
│   │   ├── intro/             # Welcome screen
│   │   │   └── IntroScreen.js
│   │   ├── home/              # Main dashboard
│   │   │   └── HomeScreen.js
│   │   ├── pokedex/           # Pokémon listing & details
│   │   │   ├── PokedexListScreen.js
│   │   │   └── DetailsScreen.js
│   │   └── scanner/           # Camera & AI detection
│   │       ├── ScannerScreen.js
│   │       └── pokedexData.js
│   │
│   ├── hooks/                 # Custom React hooks (service layer)
│   │   ├── useCamera.js       # Camera permissions & device
│   │   ├── useDexterVoice.js  # Text-to-speech (Dexter voice)
│   │   └── useSound.js        # Background music & sound effects
│   │
│   ├── services/              # Pure utility functions
│   │   └── ColorService.js    # Euclidean distance & color matching
│   │
│   ├── navigation/            # React Navigation setup
│   │   └── AppRouter.js       # Stack navigator configuration
│   │
│   └── theme/                 # Design system
│       └── theme.js           # Colors, spacing, type colors
│
├── App.js                     # Root component
├── index.js                   # Entry point (registerRootComponent)
├── app.json                   # Expo configuration
├── eas.json                   # EAS Build profiles
├── package.json               # Dependencies & scripts
└── babel.confoig.js           # Babel config (worklets + reanimated)

Core Directories Explained

/src/features/ - Feature Modules

Each feature is self-contained with its screens and related logic:

intro/

• IntroScreen.js - Splash screen with theme music
• First screen shown when app launches
• Plays intro theme and transitions to Home

home/

• HomeScreen.js - Main dashboard/menu
• Navigation hub to Scanner and Pokédex List
• Background music (Route 1 loop)

pokedex/

• PokedexListScreen.js - Browse all 151 Gen 1 Pokémon
• DetailsScreen.js - Detailed Pokémon info from PokéAPI
• Displays stats, types, descriptions with Dexter voice narration

scanner/

• ScannerScreen.js - Camera interface with color detection
• Real-time frame processing with Vision Camera
• Color extraction using react-native-image-colors
• Matches detected colors to Pokémon using hue ranges
• pokedexData.js - Static Pokémon color database (hue ranges)

The scanner uses hue-based matching instead of RGB for better perceptual accuracy. Each Pokémon has a colorRange with hueMin and hueMax values (0-360°).

/src/hooks/ - Custom Hooks

Reusable React hooks that encapsulate complex logic:

useCamera.js

// Camera device selection & permissions
const { device, hasPermission } = useCamera();

• Provides useCameraDevice('wide-angle-camera')
• Checks camera permissions with useCameraPermission()

useDexterVoice.js

// Text-to-speech with Spanish Latin voice
const { hablarEntrada, detenerVoz } = useDexterVoice();

• Uses expo-speech with Spanish (es-MX) configuration
• Custom pitch (0.57) and rate (1.2) for robotic voice
• Cleans text formatting (removes \f characters)

useSound.js

// Background music & sound effects
const { playSound, setupRouteOne, playIntro } = useSound();

• Manages audio playback with expo-av
• Handles looping background music
• Configures audio mode for iOS silent mode

/src/services/ - Pure Functions

ColorService.js

Utility functions for color matching algorithms:

ColorService.getDistance(color1, color2)
// Euclidean distance: √((r2-r1)² + (g2-g1)² + (b2-b1)²)

ColorService.findClosestPokemon(targetColor, pokemonPalette)
// Returns Pokémon with minimum color distance

The Euclidean distance formula works in 3D RGB space. Note: The actual scanner implementation uses HSL hue range matching rather than RGB Euclidean distance for better color family grouping.

/src/navigation/ - Routing

AppRouter.js

Stack-based navigation with React Navigation 7:

Intro (no header) → Home → Scanner
                          → PokedexList → Details

Screens:

• Intro - Splash screen (headerShown: false)
• Home - Main menu
• Scanner - Camera scanner
• PokedexList - Pokémon grid
• Details - Individual Pokémon info

/src/theme/ - Design System

theme.js

Centralized theme configuration:

theme.colors.primary        // #f44336 (Pokédex red)
theme.colors.secondary      // #3b4cca (Blue accent)
theme.colors.accent         // #ffde00 (Pikachu yellow)

theme.colors.types.fire     // #f08030 (Type colors)
theme.colors.scanner.target // #00e5ff (Scanner UI)

theme.spacing.md            // 16px
theme.borderRadius.lg       // 16px

Configuration Files

app.json

Expo configuration:

• App name: “Pokedex-Fleek”
• New Architecture enabled: true
• Camera permissions for iOS/Android
• Plugins: react-native-vision-camera, react-native-video
• EAS Project ID: 48249dfc-e43a-4b6c-bb06-0f1ac9742e05

eas.json

Build profiles:

• development - Dev builds with developmentClient
• preview - Internal distribution
• production - Auto-increment version numbers

babel.confoig.js

Critical plugins for worklets:

plugins: [
  ['react-native-worklets-core/plugin'],
  'react-native-reanimated/plugin', // Must be last!
]

react-native-reanimated/plugin must always be the last plugin in the array. This is required for frame processors to work correctly.

Adding New Features

Best Practices

1. Create a new feature directory:

   mkdir src/features/your-feature
   touch src/features/your-feature/YourFeatureScreen.js
   

2. Add route to AppRouter.js:

   import { YourFeatureScreen } from '../features/your-feature/YourFeatureScreen';
   
   <Stack.Screen 
     name="YourFeature" 
     component={YourFeatureScreen} 
     options={{ title: 'Your Title' }} 
   />
   

3. Extract reusable logic to hooks:

   // src/hooks/useYourLogic.js
   export const useYourLogic = () => {
     // Business logic here
     return { data, actions };
   };
   

4. Use theme constants:

   import { theme } from '../../theme/theme';
   
   <View style={{ backgroundColor: theme.colors.surface }} />
   

5. Keep screens focused:

   • Screens should handle UI and navigation only
   • Move complex logic to hooks or services
   • Keep feature folders small and focused

Example Feature Structure

src/features/team-builder/
├── TeamBuilderScreen.js      # Main screen
├── components/               # Feature-specific components
│   ├── PokemonCard.js
│   └── TypeBadge.js
├── hooks/                    # Feature-specific hooks
│   └── useTeamBuilder.js
└── utils/                    # Feature-specific utilities
    └── typeEffectiveness.js

Import Paths

Recommended Import Structure

// React & React Native
import React, { useState, useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';

// Third-party libraries
import { useNavigation } from '@react-navigation/native';
import { Camera } from 'react-native-vision-camera';

// Local imports (relative paths)
import { theme } from '../../theme/theme';
import { useCamera } from '../../hooks/useCamera';
import { ColorService } from '../../services/ColorService';

Key Dependencies

Package	Purpose	Location Used
react-navigation	Navigation	AppRouter.js
react-native-vision-camera	Camera API	Scanner
react-native-image-colors	Color extraction	Scanner
expo-speech	Text-to-speech	Details, Voice hook
expo-av	Audio playback	Sound hook
react-native-reanimated	Animations	Frame processors
react-native-worklets-core	JS worklets	Scanner frame processing
nativewind	Tailwind CSS	(Optional, not actively used)

Architecture Principles

Separation of Concerns

• Features = UI + Navigation logic
• Hooks = Reusable business logic
• Services = Pure utility functions
• Theme = Design tokens

Feature Independence

Each feature folder should be self-contained and could theoretically be extracted into its own package.

Progressive Enhancement

Start simple, add complexity only when needed. Don’t over-engineer early.

Next Steps

Running Locally

Set up your development environment

Building the App

Create production builds with EAS