{"id":31574729,"url":"https://github.com/jackmisner/brewtrackerandroid","last_synced_at":"2026-05-02T11:43:56.660Z","repository":{"id":310725798,"uuid":"1031781843","full_name":"jackmisner/BrewTrackerAndroid","owner":"jackmisner","description":"A React Native mobile app for the BrewTracker homebrewing platform, built with Expo.","archived":false,"fork":false,"pushed_at":"2025-09-29T13:22:23.000Z","size":4582,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-29T15:26:24.689Z","etag":null,"topics":["beer","beerxml","brewing-recipes","hobby-project","homebrew","open-source","react-native","solo-project","typescript"],"latest_commit_sha":null,"homepage":"https://www.brewtracker.co.uk","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jackmisner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T10:18:17.000Z","updated_at":"2025-09-27T23:00:14.000Z","dependencies_parsed_at":"2025-08-19T22:23:00.594Z","dependency_job_id":"699be604-7b3e-4b67-8a01-6de161548176","html_url":"https://github.com/jackmisner/BrewTrackerAndroid","commit_stats":null,"previous_names":["jackmisner/brewtrackerandroid"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/jackmisner/BrewTrackerAndroid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackmisner%2FBrewTrackerAndroid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackmisner%2FBrewTrackerAndroid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackmisner%2FBrewTrackerAndroid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackmisner%2FBrewTrackerAndroid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jackmisner","download_url":"https://codeload.github.com/jackmisner/BrewTrackerAndroid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackmisner%2FBrewTrackerAndroid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278486275,"owners_count":25994941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beer","beerxml","brewing-recipes","hobby-project","homebrew","open-source","react-native","solo-project","typescript"],"created_at":"2025-10-05T16:58:11.518Z","updated_at":"2026-05-02T11:43:56.645Z","avatar_url":"https://github.com/jackmisner.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BrewTracker Android\n\nA production-ready React Native mobile app for the BrewTracker homebrewing platform, built with Expo. Features comprehensive offline-first architecture, advanced brewing tools, and seamless synchronization with the Flask backend.\n\n**Version:** 2.7.5 | **Platform:** Android | **Architecture:** React Native 0.81.4 + Expo 54\n\n## Table of Contents\n\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [Architecture](#architecture)\n- [Development](#development)\n- [Building for Production](#building-for-production)\n- [Offline Functionality](#offline-functionality)\n- [Development Achievements](#development-achievements--architecture)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n### Core Functionality\n\n- **Recipe Management**: Create, edit, delete, and clone recipes with 4-step wizard\n- **Brew Session Tracking**: Track brewing sessions with fermentation data and interactive charts\n- **BeerXML Support**: Import and export recipes with ingredient matching workflow\n- **Version History**: Track recipe versions with visual timeline and navigation\n- **Brewing Calculators**: ABV, dilution, strike water, hydrometer correction, unit converter, boil timer\n- **Beer Style Analysis**: Real-time recipe comparison against style guidelines with match percentage and spec-by-spec breakdown\n\n### Offline-First Architecture\n\n- **Complete Offline Support**: Work without internet connection\n- **Automatic Synchronization**: Background sync when network returns\n- **Version-Based Caching**: Smart cache invalidation for ingredients and beer styles\n- **Conflict Resolution**: Last-write-wins strategy for concurrent edits\n- **Pending Operation Queue**: Retry logic with exponential backoff\n\n### User Experience\n\n- **Theme Support**: Light/dark mode with automatic system detection\n- **Touch-Optimized**: 48dp touch targets for comfortable mobile interaction\n- **Context Menus**: Long-press actions for recipes and brew sessions\n- **Gesture Navigation**: Swipe gestures and smooth animations\n- **Responsive Design**: Support for various screen sizes including foldables\n\n### Security \u0026 Authentication\n\n- **JWT Authentication**: Secure token storage in Expo SecureStore (hardware-backed encryption)\n- **Biometric Authentication**: Fingerprint/face recognition login with token refresh (no password required after setup)\n- **Token Preservation**: JWT tokens preserved during logout when biometrics enabled for seamless re-authentication\n- **Biometric Enrollment Modal**: Dashboard-based enrollment prompt after first successful login\n- **Email Verification**: Complete registration flow with email confirmation\n- **Password Reset**: Forgot password workflow with token validation\n- **Secure API**: Hardened API service with retry logic and error normalization\n- **Comprehensive Logging**: UnifiedLogger integration for complete authentication flow debugging\n\n### Brewing Tools\n\n- **Real-Time Calculations**: Live recipe metrics as you edit\n- **Fermentation Tracking**: Interactive charts with dual-axis display\n- **Dry Hop Tracker**: Track hop additions during fermentation\n- **Ingredient Database**: Search and filter comprehensive ingredient library\n- **Beer Style Analysis**: Real-time comparison of recipe metrics against style specifications\n- **Unit Conversion**: Seamless imperial/metric conversion\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js 18+** and npm\n- **Expo CLI**: `npm install -g @expo/cli`\n- **Android Device or Emulator**: Physical device or Android Studio\n- **BrewTracker Backend**: Flask backend must be running (see main project README)\n\n### Installation \u0026 Setup\n\n```bash\n# 1. Navigate to the project directory\ncd BrewTrackerAndroid\n\n# 2. Install dependencies\nnpm install\n\n# 3. Configure environment variables\ncp .env.example .env\n\n# 4. Update .env with your backend IP address\n# For physical devices:\nEXPO_PUBLIC_API_URL=http://192.168.1.100:5000/api\n# For Android emulators:\nEXPO_PUBLIC_API_URL=http://10.0.2.2:5000/api\n\n# 5. Start the Flask backend with network access\n# (In the BrewTracker backend directory)\nflask run --host=0.0.0.0\n\n# 6. Start the Expo development server\nnpm start\n```\n\n### Development Workflow\n\n```bash\n# Run type checking\nnpm run type-check\n\n# Run linter (oxlint - 100x faster)\nnpm run lint\n\n# Run tests\nnpm test\n\n# Run tests with coverage\nnpm run coverage\n\n# Format code\nnpm run format\n```\n\n### First Time Setup\n\n1. **Physical Device**: Install Expo Go from Google Play Store\n2. **Scan QR Code**: Use Expo Go to scan the QR code from `npm start`\n3. **Android Emulator**: Press 'a' in the terminal after `npm start`\n4. **Create Account**: Register a new account in the app\n5. **Verify Email**: Check your email for verification link (if backend email is configured)\n\n## Architecture\n\n## Project Structure\n\n```\nBrewTrackerAndroid/                                   # React Native Android application\n├── app/                                              # Expo Router file-based routing structure\n│   ├── (auth)/                                       # Authentication flow screens\n│   │   ├── _layout.tsx                               # Authentication stack layout configuration\n│   │   ├── login.tsx                                 # Login screen with JWT + biometric auth, sets enrollment flags\n│   │   ├── register.tsx                              # User registration with real-time validation\n│   │   ├── verifyEmail.tsx                           # Email verification with token input and resend functionality\n│   │   ├── forgotPassword.tsx                        # Password reset request with email validation\n│   │   └── resetPassword.tsx                         # Password reset confirmation with token validation\n│   ├── (tabs)/                                       # Main application tab navigation\n│   │   ├── _layout.tsx                               # Tab navigation layout with Material Icons\n│   │   ├── index.tsx                                 # Dashboard with BiometricEnrollmentModal, brewing overview, recent activity\n│   │   ├── recipes.tsx                               # Recipe management and browsing with search and filtering\n│   │   ├── brewSessions.tsx                          # Brew session tracking and management with status filtering\n│   │   ├── utilities.tsx                             # Brewing calculators and utility tools grid\n│   │   └── profile.tsx                               # User profile and settings with secure logout\n│   ├── (modals)/                                     # Modal/detail screens (not in tab navigation)\n│   │   ├── _layout.tsx                               # Modal navigation layout configuration\n│   │   ├── (recipes)/                                # Recipe-related detail and creation screens\n│   │   │   ├── _layout.tsx                           # Recipe modals stack layout\n│   │   │   ├── viewRecipe.tsx                        # Individual recipe detail view with ingredients and metrics\n│   │   │   ├── createRecipe.tsx                      # Multi-step recipe creation wizard (4 steps)\n│   │   │   ├── editRecipe/[id].tsx                   # Recipe editing interface with dynamic route parameter\n│   │   │   ├── versionHistory.tsx                    # Recipe version history timeline navigation\n│   │   │   └── ingredientPicker.tsx                  # Full-screen ingredient selection with search and filtering\n│   │   ├── (beerxml)/                                # BeerXML import/export workflow screens\n│   │   │   ├── importBeerXML.tsx                     # BeerXML file selection and parsing\n│   │   │   ├── ingredientMatching.tsx                # Ingredient matching and approval workflow\n│   │   │   └── importReview.tsx                      # Final import review and recipe creation\n│   │   ├── (brewSessions)/                           # Brew session detail screens\n│   │   │   ├── _layout.tsx                           # Brew session modals stack layout\n│   │   │   ├── viewBrewSession.tsx                   # Individual brew session detail view with metrics and status\n│   │   │   ├── createBrewSession.tsx                 # Multi-step brew session creation wizard\n│   │   │   ├── editBrewSession/[id].tsx              # Brew session editing interface with dynamic route parameter\n│   │   │   ├── addFermentationEntry.tsx              # Add new fermentation data entries with validation\n│   │   │   └── editFermentationEntry/[id].tsx        # Fermentation entry editing interface with dynamic route parameter\n│   │   ├── (calculators)/                            # Brewing calculator tools\n│   │   │   ├── _layout.tsx                           # Calculator modals stack layout\n│   │   │   ├── abv.tsx                               # ABV (Alcohol by Volume) calculator\n│   │   │   ├── dilution.tsx                          # Water dilution calculator\n│   │   │   ├── strikeWater.tsx                       # Strike water temperature calculator\n│   │   │   ├── hydrometerCorrection.tsx              # Hydrometer temperature correction calculator\n│   │   │   ├── unitConverter.tsx                     # Unit conversion calculator (volume, weight, temperature)\n│   │   │   └── boilTimer.tsx                         # Boil timer with hop addition alerts and notifications\n│   │   └── (settings)/                               # Settings screens\n│   │       ├── _layout.tsx                           # Settings modals stack layout\n│   │       └── settings.tsx                          # User settings and preferences (units, theme, notifications)\n│   ├── index.tsx                                     # Entry point with auth routing and splash screen\n│   └── _layout.tsx                                   # Root layout with providers (Auth, Theme, Network, Query)\n├── src/                                              # Source code for React Native components and services\n│   ├── components/                                   # Reusable UI components organized by feature\n│   │   ├── boilTimer/                                # Boil timer specific components\n│   │   │   └── RecipeSelector.tsx                    # Recipe selection component for boil timer with search\n│   │   ├── brewSessions/                             # Brew session specific components\n│   │   │   ├── DryHopTracker.tsx                     # Dry hop additions tracker with schedule display\n│   │   │   ├── FermentationChart.tsx                 # Interactive fermentation tracking charts with dual-axis\n│   │   │   ├── FermentationData.tsx                  # Fermentation data display and management component\n│   │   │   └── FermentationEntryContextMenu.tsx      # Context menu for fermentation entry actions\n│   │   ├── calculators/                              # Brewing calculator components\n│   │   │   ├── CalculatorCard.tsx                    # Reusable calculator card component for utilities screen\n│   │   │   ├── CalculatorHeader.tsx                  # Standard calculator header with title and description\n│   │   │   ├── ResultDisplay.tsx                     # Standardized result display component for calculations\n│   │   │   ├── UnitToggle.tsx                        # Unit system toggle component for calculator inputs\n│   │   │   └── NumberInput.tsx                       # Specialized number input component for calculator forms\n│   │   ├── debug/                                    # Debug and development components\n│   │   │   └── DevIdDebugger.tsx                     # Development ID debugging component for troubleshooting\n│   │   ├── recipes/                                  # Recipe management components\n│   │   │   ├── BrewingMetrics/                       # Recipe metrics display components\n│   │   │   │   └── BrewingMetricsDisplay.tsx         # Reusable brewing metrics with SRM color visualization\n│   │   │   ├── IngredientEditor/                     # Advanced ingredient editing components\n│   │   │   │   └── IngredientDetailEditor.tsx        # Complete ingredient editing with type-specific UI\n│   │   │   ├── RecipeForm/                           # Multi-step recipe creation forms\n│   │   │   │   ├── BasicInfoForm.tsx                 # Recipe name, style, batch size input (Step 1)\n│   │   │   │   ├── ParametersForm.tsx                # Brewing parameters (boil time, efficiency, mash temp) (Step 2)\n│   │   │   │   ├── IngredientsForm.tsx               # Ingredient list management interface (Step 3)\n│   │   │   │   └── ReviewForm.tsx                    # Final recipe review and submission (Step 4)\n│   │   │   └── StyleAnalysis.tsx                     # Real-time beer style adherence analysis with match percentage and spec breakdown\n│   │   ├── splash/                                   # Splash screen components\n│   │   │   └── SplashScreen.tsx                      # App loading splash screen component with animations\n│   │   ├── ui/                                       # Generic UI components\n│   │   │   ├── ContextMenu/                          # Context menu implementations\n│   │   │   │   ├── BaseContextMenu.tsx               # Base context menu component with common functionality\n│   │   │   │   ├── RecipeContextMenu.tsx             # Recipe-specific context menu actions (view, edit, delete, clone, version)\n│   │   │   │   ├── BrewSessionContextMenu.tsx        # Brew session-specific context menu actions (view, edit, delete)\n│   │   │   │   └── contextMenuUtils.ts               # Shared utilities for context menu operations\n│   │   │   └── ModalHeader.tsx                       # Reusable modal header component with close button\n│   │   ├── BiometricEnrollmentModal.tsx              # Dashboard biometric enrollment prompt after first login\n│   │   └── NetworkStatusBanner.tsx                   # Network connectivity status banner component with online/offline indicator\n│   ├── contexts/                                     # React contexts for global state\n│   │   ├── AuthContext.tsx                           # Authentication with JWT, biometric auth, token preservation, UnifiedLogger\n│   │   ├── CalculatorsContext.tsx                    # Calculator state management and shared logic with useReducer\n│   │   ├── DeveloperContext.tsx                      # Developer options and debugging context for dev mode\n│   │   ├── NetworkContext.tsx                        # Network connectivity detection for offline functionality (NetInfo)\n│   │   ├── ScreenDimensionsContext.tsx               # Screen dimensions management with support for foldable devices\n│   │   ├── ThemeContext.tsx                          # Theme management with light/dark mode support\n│   │   └── UnitContext.tsx                           # Unit system management (imperial/metric) with AsyncStorage persistence\n│   ├── hooks/                                        # Custom React hooks\n│   │   ├── offlineV2/                                # V2 offline system hooks\n│   │   │   ├── index.ts                              # Centralized exports for V2 offline hooks\n│   │   │   ├── useStaticData.ts                      # Offline-first ingredients and beer styles management\n│   │   │   ├── useUserData.ts                        # Offline-first user data (recipes) management with sync\n│   │   │   ├── useOfflineSync.ts                     # Sync status monitoring and manual sync triggers\n│   │   │   └── useStartupHydration.ts                # App startup data hydration and cache warming\n│   │   ├── useDebounce.ts                            # Performance optimization for search inputs (300ms debounce)\n│   │   ├── useRecipeMetrics.ts                       # Real-time recipe calculations hook (OG, FG, ABV, IBU, SRM)\n│   │   └── useStoragePermissions.ts                  # Storage permission management for file operations\n│   ├── services/                                     # API services and business logic\n│   │   ├── api/                                      # API layer with React Query integration\n│   │   │   ├── apiService.ts                         # Hardened API service with validated base URL, timeout, error normalization, and retry logic\n│   │   │   ├── queryClient.ts                        # React Query client configuration with AsyncStorage persistence\n│   │   │   └── idInterceptor.ts                      # MongoDB ObjectId to string normalization for consistent IDs\n│   │   ├── beerStyles/                               # Beer style analysis services\n│   │   │   └── BeerStyleAnalysisService.ts           # Offline style comparison and recipe-to-style matching (OG, FG, ABV, IBU, SRM)\n│   │   ├── beerxml/                                  # BeerXML processing services\n│   │   │   └── BeerXMLService.ts                     # BeerXML import/export with mobile file integration (expo-document-picker)\n│   │   ├── offlineV2/                                # V2 offline system services\n│   │   │   ├── index.ts                              # Centralized exports for V2 offline services\n│   │   │   ├── StaticDataService.ts                  # Permanent caching of ingredients/beer styles with version-based invalidation\n│   │   │   ├── UserCacheService.ts                   # Offline-first user data CRUD with sync queue and conflict resolution\n│   │   │   ├── LegacyMigrationService.ts             # Migration utilities for V1 to V2 system transition\n│   │   │   └── StartupHydrationService.ts            # App startup data hydration and cache warming system\n│   │   ├── brewing/                                  # Brewing-specific services\n│   │   │   └── OfflineMetricsCalculator.ts           # Offline brewing calculations and recipe metrics (OG, FG, ABV, IBU, SRM)\n│   │   ├── logger/                                   # Logging and debugging services\n│   │   │   ├── Logger.ts                             # Base logging service interface\n│   │   │   ├── UnifiedLogger.ts                      # Unified logging with development and production modes\n│   │   │   └── DevLogger.ts                          # Development-specific logging with endpoint integration\n│   │   ├── debug/                                    # Debugging utilities\n│   │   │   └── DebugHelpers.ts                       # Development debugging and troubleshooting utilities\n│   │   ├── calculators/                              # Brewing calculation services\n│   │   │   ├── ABVCalculator.ts                      # Alcohol by Volume calculation logic\n│   │   │   ├── BoilTimerCalculator.ts                # Boil timer and hop addition scheduling\n│   │   │   ├── DilutionCalculator.ts                 # Water dilution and blending calculations\n│   │   │   ├── EfficiencyCalculator.ts               # Mash and brewhouse efficiency calculations\n│   │   │   ├── HydrometerCorrectionCalculator.ts     # Temperature-corrected hydrometer readings\n│   │   │   ├── PrimingSugarCalculator.ts             # Carbonation and priming sugar calculations\n│   │   │   ├── StrikeWaterCalculator.ts              # Mash strike water temperature calculations\n│   │   │   ├── UnitConverter.ts                      # Unit conversion utilities and logic (volume, weight, temperature)\n│   │   │   └── YeastPitchRateCalculator.ts           # Yeast pitching rate and viability calculations\n│   │   ├── BiometricService.ts                       # Biometric auth (fingerprint/face) with UnifiedLogger integration\n│   │   ├── config.ts                                 # Service configuration and constants (API URLs, timeouts, storage keys)\n│   │   ├── NotificationService.ts                    # Local notification service for timers and alerts (expo-notifications)\n│   │   ├── storageService.ts                         # Storage service for file operations and permissions\n│   │   └── TimerPersistenceService.ts                # Timer state persistence for boil timer (AsyncStorage)\n│   ├── constants/                                    # Shared constants and configuration\n│   │   ├── hopConstants.ts                           # Hop usage options, time presets, and type definitions\n│   │   └── testIDs.ts                                # Centralized test IDs for consistent testing across components\n│   ├── utils/                                        # Utility functions\n│   │   ├── formatUtils.ts                            # Comprehensive brewing data formatting utilities\n│   │   ├── idNormalization.ts                        # MongoDB ObjectId normalization utilities\n│   │   ├── jwtUtils.ts                               # JWT token validation and management utilities\n│   │   ├── keyUtils.ts                               # Secure key generation and management utilities\n│   │   ├── recipeUtils.ts                            # Recipe data manipulation and transformation utilities\n│   │   ├── syncUtils.ts                              # Offline sync utilities for conflict resolution\n│   │   ├── timeUtils.ts                              # Time calculation and conversion utilities\n│   │   └── userValidation.ts                         # User input validation utilities (email, password strength)\n│   ├── types/                                        # TypeScript type definitions for mobile app\n│   │   ├── api.ts                                    # API request/response interfaces\n│   │   ├── common.ts                                 # Shared utility types\n│   │   ├── recipe.ts                                 # Recipe and ingredient types\n│   │   ├── brewSession.ts                            # Brew session and fermentation types\n│   │   ├── user.ts                                   # User account and authentication types\n│   │   ├── offlineV2.ts                              # V2 offline system type definitions\n│   │   ├── logger.ts                                 # Logging system type definitions\n│   │   ├── offline.ts                                # Legacy offline types (for migration compatibility)\n│   │   └── index.ts                                  # Central type exports\n│   └── styles/                                       # StyleSheet definitions organized by feature\n│       ├── auth/                                     # Authentication screen styles\n│       │   ├── loginStyles.ts                        # Login screen styling with theme support + biometric button\n│       │   ├── registerStyles.ts                     # Registration screen styling\n│       │   └── verifyEmailStyles.ts                  # Email verification screen styling\n│       ├── tabs/                                     # Tab navigation screen styles\n│       │   ├── dashboardStyles.ts                    # Dashboard/home screen styling\n│       │   ├── recipesStyles.ts                      # Recipe list screen styling\n│       │   ├── brewSessionsStyles.ts                 # Brew session list screen styling\n│       │   └── profileStyles.ts                      # Profile screen styling\n│       ├── modals/                                   # Modal screen styles\n│       │   ├── calculators/                          # Calculator modal styles\n│       │   │   ├── boilTimerStyles.ts                # Boil timer calculator styling\n│       │   │   └── calculatorScreenStyles.ts         # Common calculator screen styling\n│       │   ├── viewRecipeStyles.ts                   # Recipe detail view styling\n│       │   ├── createRecipeStyles.ts                 # Recipe creation wizard styling\n│       │   ├── ingredientPickerStyles.ts             # Ingredient picker styling\n│       │   ├── viewBrewSessionStyles.ts              # Brew session detail view styling\n│       │   ├── createBrewSessionStyles.ts            # Brew session creation styling\n│       │   ├── editBrewSessionStyles.ts              # Brew session editing styling\n│       │   └── settingsStyles.ts                     # Settings screen styling\n│       ├── components/                               # Component-specific styles\n│       │   ├── brewingMetricsStyles.ts               # Brewing metrics display styling\n│       │   ├── brewSessions/                         # Brew session component styles\n│       │   │   └── dryHopTrackerStyles.ts            # Dry hop tracker component styling\n│       │   ├── calculators/                          # Calculator component styles\n│       │   │   ├── calculatorCardStyles.ts           # Calculator card component styling\n│       │   │   ├── calculatorHeaderStyles.ts         # Calculator header component styling\n│       │   │   ├── numberInputStyles.ts              # Number input component styling\n│       │   │   ├── resultDisplayStyles.ts            # Result display component styling\n│       │   │   └── unitToggleStyles.ts               # Unit toggle component styling\n│       │   ├── charts/                               # Chart component styles\n│       │   │   └── fermentationChartStyles.ts        # Fermentation chart styling\n│       │   └── modalHeaderStyles.ts                  # Modal header component styling\n│       ├── recipes/                                  # Recipe component styles\n│       │   └── ingredientDetailEditorStyles.ts       # Ingredient editor styling\n│       ├── components/styleAnalysisStyles.ts         # Style analysis component styling with color-coded match indicators\n│       ├── ui/                                       # UI component styles\n│       │   ├── baseContextMenuStyles.ts              # Base context menu styling\n│       │   └── recipeContextMenuStyles.ts            # Recipe context menu styling\n│       └── common/                                   # Shared styling utilities\n│           ├── colors.ts                             # Theme color definitions (light/dark mode)\n│           ├── buttons.ts                            # Reusable button styles\n│           └── sharedStyles.ts                       # Common shared styling utilities\n├── tests/                                            # Comprehensive test suite (3218 tests across 131 suites)\n├── plugins/                                          # Expo config plugins\n│   ├── withConditionalNetworkSecurity.js             # Network security configuration for development/production\n│   └── withSingleTaskLaunchMode.js                   # Android launch mode configuration\n├── scripts/                                          # Build and development scripts\n│   ├── build-helper.js                               # Environment-specific build configuration\n│   ├── build-info.js                                 # Display current build information\n│   ├── bump-version.js                               # Version bumping script (patch/minor/major)\n│   └── detect-ip.js                                  # Auto-detect local IP for development\n├── assets/                                           # Static assets (images, fonts, icons)\n├── app.json                                          # Expo configuration (Android-only, New Architecture enabled)\n├── package.json                                      # Dependencies and scripts\n├── eas.json                                          # EAS Build configuration (dev/preview/production)\n├── eslint.config.js                                  # ESLint configuration (fallback linter)\n├── .oxlintrc.json                                    # oxlint configuration (primary linter - 100x faster)\n├── tsconfig.json                                     # TypeScript configuration with path aliases (@/, @services/, etc.)\n├── jest.config.js                                    # Jest testing configuration\n├── metro.config.js                                   # Metro bundler configuration\n├── babel.config.js                                   # Babel configuration with module resolver\n├── dev-log-server.js                                 # Development log server for mobile debugging\n├── expo-env.d.ts                                     # Expo TypeScript environment definitions\n├── LICENSE                                           # GPL-3.0-or-later license\n├── LICENSE-HEADER.txt                                # License header for source files\n└── .env                                              # Environment variables (API URL, debug mode, etc.)\n```\n\n### Key Technologies\n\n**Core Framework:**\n\n- **React 19.1.0**: Latest React with concurrent features\n- **React Native 0.81.4**: Modern React Native with New Architecture enabled\n- **Expo 54**: Complete development platform with OTA updates\n- **TypeScript 5.9.2**: Full type safety with strict mode\n\n**Navigation \u0026 State:**\n\n- **Expo Router 6.0**: File-based navigation with typed routes\n- **React Query 5.87**: Server state with offline persistence\n- **Expo Secure Store**: Encrypted JWT token storage\n- **AsyncStorage 2.2**: Local data persistence\n\n**Offline \u0026 Network:**\n\n- **NetInfo 11.4**: Network connectivity detection\n- **Custom Offline V2 System**: Version-based caching with sync\n- **Query Persistence**: AsyncStorage persister for React Query\n\n**UI \u0026 Animation:**\n\n- **React Native Reanimated 4.1**: High-performance animations\n- **React Native Gesture Handler 2.28**: Touch and gesture handling\n- **React Native Gifted Charts 1.4**: Interactive fermentation charts\n- **@expo/vector-icons**: Material Icons for consistent UI\n\n**Development Tools:**\n\n- **oxlint 1.14**: Ultra-fast Rust-based linter (100x faster than ESLint)\n- **Jest 29.7**: Testing framework with 3148 passing tests\n- **Prettier 3.4**: Code formatting\n- **EAS Build**: Production builds with OTA updates\n\n### File Organization Conventions\n\n- **camelCase**: All TypeScript files use camelCase naming (e.g., `verifyEmail.tsx`, `brewSessions.tsx`)\n- **Route Groups**: Parentheses `()` create logical groupings without affecting URLs:\n  - `(auth)/` - Authentication screens\n  - `(tabs)/` - Main tab navigation screens\n  - `(modals)/` - Detail/overlay screens not in tab navigation\n- **Feature Grouping**: Modal screens are grouped by feature under `(modals)/(feature)/`\n- **Consistent Structure**: Follows TypeScript and React Native best practices\n\n### State Management\n\n- **Authentication**: React Context with Expo SecureStore for JWT tokens\n- **Network Connectivity**: React Context with NetInfo for offline detection\n- **Screen Dimensions**: React Context with support for foldable devices\n- **Theme Management**: React Context with AsyncStorage persistence\n- **Unit System**: React Context for imperial/metric conversion\n- **Server Data**: React Query with AsyncStorage persistence for offline support\n- **Offline Data**: AsyncStorage with React Query integration for seamless offline/online experience\n- **Local State**: React hooks (useState, useReducer) for component-level state\n\n### Styling Architecture\n\nThe app uses a centralized styling system with theme support:\n\n- **Theme Context**: Light/dark mode support with automatic system detection\n- **Feature-based Organization**: Styles are organized by screen type (auth, tabs, modals)\n- **Dynamic Theming**: All style functions accept theme context for consistent theming\n- **TypeScript Integration**: All styles are fully typed with theme-aware interfaces\n- **Centralized Colors**: Theme-based color system with light/dark variants\n- **Responsive Design**: Proper spacing, typography, and touch targets for mobile\n\n#### Theme-Aware Style Pattern:\n\n```typescript\nimport { useTheme } from \"@contexts/ThemeContext\";\nimport { viewBrewSessionStyles } from \"@styles/modals/viewBrewSessionStyles\";\n\nconst theme = useTheme();\nconst styles = viewBrewSessionStyles(theme);\n```\n\nThis approach provides:\n\n- **Theme Consistency**: All screens automatically adapt to light/dark themes\n- **Maintainability**: Styles are separate from component logic with theme support\n- **Accessibility**: Proper contrast ratios and readable text in both themes\n- **Type Safety**: Full TypeScript support for all style properties and theme values\n\n## Development\n\n### Available Scripts\n\n- `npm start` - Start Expo development server\n- `npm run android` - Build and run on Android device/emulator\n- `npm run lint` - Run oxlint (100x faster than ESLint)\n- `npm run lint:fix` - Run oxlint with auto-fix\n- `npm run lint:eslint` - Fallback to ESLint if needed\n- `npm run lint:eslint:fix` - ESLint with auto-fix\n- `npm run type-check` - Run TypeScript type checking\n- `npm run format` - Format code with Prettier\n- `npm run format:check` - Check code formatting\n- `npm test` - Run test suite\n- `npm run test:watch` - Run tests in watch mode\n- `npm run coverage` - Run tests with coverage report\n- `npm run test:ci` - Run tests for CI/CD with coverage\n- `npm run version:patch` - Increment patch version and sync with app.json\n- `npm run version:minor` - Increment minor version and sync with app.json\n- `npm run version:major` - Increment major version and sync with app.json\n\n### Code Quality \u0026 Testing\n\n- **TypeScript**: Strict type checking with `npm run type-check` (must pass for all commits)\n- **Linting**: oxlint primary linter (100x faster than ESLint), ESLint fallback available\n- **Testing**: Comprehensive test suite with 3218 passing tests across 131 test suites\n- **Test Coverage**: High coverage across all critical paths including authentication and biometrics\n- **Quality Gates**: All CRUD operations, advanced features, and UI components fully tested\n- **CI/CD**: Automated quality checks ensure code standards\n\n### Environment Variables\n\nConfigure in `.env`:\n\n- `EXPO_PUBLIC_API_URL` - Backend API URL (required)\n- `EXPO_PUBLIC_DEBUG_MODE` - Enable debug logging (optional)\n- `EXPO_PUBLIC_LOG_LEVEL` - Set logging level (optional)\n- `EXPO_PUBLIC_ENABLE_GOOGLE_AUTH` - Enable Google authentication (optional)\n- `EXPO_PUBLIC_ENABLE_OFFLINE_MODE` - Enable offline features (enabled by default)\n- `EXPO_PUBLIC_ANALYTICS_ENABLED` - Enable analytics tracking (optional)\n\n### Backend Integration\n\nThe app connects to the BrewTracker Flask backend. Ensure the backend is running and accessible from your mobile device's network.\n\n#### Network Configuration\n\nFlask defaults to port 5000. If you've changed the backend port, update both the Flask command and API URL accordingly.\n\n**For Physical Devices:** Use your computer's network IP address instead of `localhost`:\n\n```\nEXPO_PUBLIC_API_URL=http://192.168.1.100:5000/api\n```\n\n**For Android Emulators:** You can use the special IP address `10.0.2.2` which maps to the host machine's `localhost`:\n\n```\nEXPO_PUBLIC_API_URL=http://10.0.2.2:5000/api\n```\n\n**Important Setup Steps:**\n\n1. Start the backend with `--host=0.0.0.0` to accept connections from mobile devices:\n\n```bash\n# In the BrewTracker backend directory\nflask run --host=0.0.0.0\n```\n\n2. **Firewall Configuration:** When testing on physical devices, ensure port 5000 (or your custom port) is open in your computer's firewall settings to allow incoming connections from mobile devices on your network.\n\n## Building for Production\n\n### Production Build Scripts\n\nThe app includes automated build scripts for development, preview, and production builds:\n\n```bash\n# Build for development (includes debug tools)\nnpm run build:dev\n\n# Build for preview (production mode with debug)\nnpm run build:preview\n\n# Build for production (optimized release)\nnpm run build:prod\n\n# Build all profiles\nnpm run build:all\n```\n\n### Environment Management\n\n```bash\n# Set development environment (auto-detects local IP)\nnpm run env:dev\n\n# Set production environment (uses production API)\nnpm run env:prod\n\n# Display current build information\nnpm run build:info\n```\n\n### EAS Build Configuration\n\nThe app uses Expo Application Services (EAS) for builds:\n\n- **Development builds**: Include dev tools, connect to local backend\n- **Preview builds**: Production mode with debugging enabled\n- **Production builds**: Optimized for Google Play Store release\n\n## API Security \u0026 Hardening\n\nThe BrewTrackerAndroid API service layer has been hardened with robust security and reliability features:\n\n### Configuration Validation\n\n- **Mandatory Base URL**: `EXPO_PUBLIC_API_URL` environment variable is strictly required and validated\n- **URL Format Validation**: Ensures API URL is properly formatted and accessible\n- **Clean URL Processing**: Automatic trailing slash removal for consistency\n- **Fail-Fast Validation**: Application fails immediately with clear error messages for invalid configuration\n\n### Enhanced Error Handling\n\n- **Error Normalization**: Consistent error format across all API responses\n- **Categorized Errors**: Network errors, timeouts, client errors, and server errors properly classified\n- **User-Friendly Messages**: Technical errors translated to actionable user messages\n- **Retryability Detection**: Automatic identification of retryable vs non-retryable errors\n\n### Network Resilience\n\n- **Smart Retry Policy**: Automatic retry for idempotent GET requests on transient failures\n- **Exponential Backoff**: Progressive retry delays with jitter to prevent thundering herd\n- **Timeout Configuration**: Hardened 15-second timeout optimized for mobile networks\n- **Connection Validation**: Built-in network connectivity checking\n\n### Error Types Handled\n\n- **Network Errors**: Connection failures, DNS issues, network timeouts\n- **HTTP Status Codes**: Proper handling of 4xx client errors and 5xx server errors\n- **Rate Limiting**: Automatic retry for 429 (Too Many Requests) responses\n- **Service Unavailability**: Retry logic for 502, 503, 504 temporary service issues\n- **Authentication**: Secure token cleanup on 401 authentication failures\n\n### Usage Example\n\n```typescript\n// Error handling with normalization\ntry {\n  const recipe = await ApiService.recipes.getById(\"recipe-id\");\n} catch (error) {\n  const normalized = ApiService.handleApiError(error);\n\n  if (normalized.isRetryable) {\n    // Will be automatically retried for GET requests\n    console.log(\"Retrying request...\");\n  } else {\n    // Handle non-retryable errors\n    showUserError(normalized.message);\n  }\n}\n```\n\n### Configuration Requirements\n\n```bash\n# Required in .env file\nEXPO_PUBLIC_API_URL=https://api.brewtracker.com/v1  # Must be valid URL\nEXPO_PUBLIC_DEBUG_MODE=false                        # Optional debug logging\n```\n\n## **Offline Functionality**\n\n### **V2 System Complete: Comprehensive Offline-First Architecture**\n\nBrewTrackerAndroid features a fully implemented V2 offline-first system with comprehensive caching, version-based synchronization, and automatic conflict resolution, ensuring brewers can work seamlessly regardless of network connectivity.\n\n#### **V2 System Capabilities**\n\n**Complete Static Data Management:**\n\n- **Permanent Caching**: Ingredients and beer styles cached indefinitely with version-based invalidation\n- **Background Version Checking**: Automatic version comparison with 30-second cooldown periods\n- **Smart Cache Updates**: Only downloads data when backend versions change\n- **Instant Access**: Static data available immediately without network requests\n\n**Advanced User Data Synchronization:**\n\n- **Offline-First CRUD**: Complete recipe operations work without internet connection\n- **Pending Operation Queue**: Offline changes queued with retry logic and exponential backoff\n- **Conflict Resolution**: Last-write-wins strategy with timestamp-based merging\n- **Tombstone Deletion**: Proper sync handling for deleted items\n\n**Comprehensive Startup System:**\n\n- **App Hydration**: Automatic cache warming and data preparation on app launch\n- **Legacy Migration**: Seamless transition from V1 to V2 system with data preservation\n- **Performance Optimization**: Efficient startup with background data loading\n\n#### **V2 Technical Architecture**\n\n**Core V2 Services:**\n\n- `StaticDataService.ts` - Permanent caching with version-based invalidation for ingredients and beer styles\n- `UserCacheService.ts` - Offline-first user data CRUD with sync queue and conflict resolution\n- `StartupHydrationService.ts` - App startup data hydration and cache warming system\n- `LegacyMigrationService.ts` - Migration utilities for V1 to V2 system transition\n\n**Advanced React Hooks:**\n\n- `useStaticData()` - Combined ingredients and beer styles management with background refresh\n- `useUserData()` - User recipe CRUD with offline support and authentication\n- `useOfflineSync()` - Sync status monitoring and manual sync triggers\n- `useStartupHydration()` - App startup data hydration and cache management\n\n**Robust Type System:**\n\n- `offlineV2.ts` - Complete type definitions for caching, sync, and conflict resolution\n- `logger.ts` - Comprehensive logging system types for debugging and monitoring\n\n#### **V2 User Experience**\n\n**Seamless Performance:**\n\n- **Instant Responses**: All data operations respond immediately from local cache\n- **Zero Loading States**: Cached static data eliminates loading spinners\n- **Background Sync**: Network operations happen transparently without user interruption\n- **Automatic Recovery**: Failed operations retry automatically when network improves\n\n**Advanced Sync Management:**\n\n- **Real-time Status**: Comprehensive sync status monitoring with user-friendly messages\n- **Manual Control**: Optional manual sync triggers for immediate synchronization\n- **Visual Indicators**: Clear indication of pending changes and sync progress\n- **Error Recovery**: Automatic retry with user notification for persistent failures\n\n#### **V2 Testing Coverage**\n\n**Comprehensive Offline V2 Test Suite (126 Tests):**\n\n- `StaticDataService.test.ts` (23 tests) - Version checking, caching, and filtering\n- `UserCacheService.test.ts` (36 tests) - CRUD operations, sync queue, and conflict resolution\n- `useStaticData.test.tsx` (25 tests) - Hook functionality and cache management\n- `useUserData.test.tsx` (24 tests) - User data operations and sync integration\n- `useOfflineSync.test.tsx` (18 tests) - Sync status monitoring and manual triggers\n- Plus startup hydration, legacy migration, and integration tests\n\n**Data Integrity \u0026 Performance:**\n\n- **Version-Based Cache Invalidation**: Prevents stale data with backend version comparison\n- **Offline Data Persistence**: All data survives app restarts and device reboots\n- **Sync Conflict Resolution**: Robust handling of concurrent edits across devices\n- **Performance Optimization**: Efficient cache management with memory and storage optimization\n\n**Overall Test Suite:** 3218 passing tests across 131 test suites covering all features\n\n---\n\n## **Development Achievements \u0026 Architecture**\n\n### **Phase 5 Completion Status: ~85% Feature Parity**\n\n### Core Features Complete\n\n- **Authentication**: Complete login/register flow with email verification and secure JWT token storage in Expo SecureStore\n- **Offline Recipe Management**: Complete offline-first recipe CRUD with automatic background synchronization\n- **Recipe Cloning System**: Differentiated logic for private recipes (versioning) vs public recipes (attribution with original author)\n- **Version History**: Complete timeline navigation with visual version tree and interactive browsing\n- **BeerXML Import/Export**: 3-screen mobile workflow with ingredient matching, file sharing, and export functionality\n- **Brew Session Tracking**: Full CRUD operations with comprehensive fermentation data management and interactive charts as well as Dry Hop tracking/management\n- **Brewing Calculators**: ABV, dilution, strike water, hydrometer correction, unit converter, and boil timer with notifications\n- **Beer Style Analysis**: Offline recipe-to-style comparison with match percentage, spec-by-spec breakdown, and match quality categorization\n- **Advanced UI/UX**: Touch-optimized interface (48dp targets), context menus, gesture navigation, and comprehensive theme support\n- **Testing Infrastructure**: 3218 passing tests across 131 test suites with comprehensive coverage\n\n### Advanced Technical Features\n\n- **V2 Offline-First Architecture**: Comprehensive caching with version-based invalidation and automatic sync\n- **React Query Integration**: Optimistic updates, cache invalidation, background sync, and offline persistence\n- **Automatic Synchronization**: Background sync when network becomes available with conflict resolution\n- **Network Detection**: Real-time connectivity monitoring with automatic fallback behavior\n- **Secure Storage**: JWT tokens in Expo SecureStore (not localStorage)\n- **Mobile-First Design**: 48dp touch targets, responsive layouts, foldable device support\n- **Network Resilience**: Hardened API service with retry logic and error normalization\n- **Type Safety**: Full TypeScript coverage with strict type checking\n\n### Phase 5+ Roadmap: Final Feature Parity (~15% Remaining)\n\n**Current Focus:** Implementing final advanced features to achieve 100% web app parity\n\n#### High Priority Missing Features:\n\n- **AI Optimization Engine**: Recipe analysis and improvement suggestions\n- **Advanced Analytics**: Brewing dashboard and comprehensive reporting\n- **Advanced Ingredient Management**: Enhanced search and filtering capabilities\n- **Push Notifications**: Real-time brew session reminders and alerts\n\n## Contributing\n\nThis is a companion app to the main BrewTracker project. Follow the same contribution guidelines as the main project.\n\n### Development Standards\n\n- **TypeScript**: All code must pass `npm run type-check` with no errors\n- **Linting**: Use `npm run lint` (oxlint) before committing\n- **Testing**: Maintain high test coverage with meaningful tests\n- **Code Style**: Use Prettier for consistent formatting (`npm run format`)\n- **Commit Messages**: Clear, descriptive commit messages\n- **Pull Requests**: Include tests and documentation for new features\n\n### Testing Requirements\n\n- All new features must include comprehensive tests\n- Bug fixes should include regression tests\n- Maintain \u003e70% code coverage\n- Tests must pass before merging: `npm test`\n\n### Architecture Principles\n\n- **Offline-First**: All features should work offline when possible\n- **Type Safety**: Leverage TypeScript's strict type checking\n- **Mobile-First**: Design for touch interaction and mobile networks\n- **Performance**: Optimize for battery life and data usage\n- **Security**: Follow secure coding practices, especially for authentication\n\n## License\n\n**GPL-3.0-or-later** - Same as the main BrewTracker project.\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackmisner%2Fbrewtrackerandroid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjackmisner%2Fbrewtrackerandroid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackmisner%2Fbrewtrackerandroid/lists"}