🍺 BrewTracker

A comprehensive brewing management application that helps homebrewers create, manage, and track their beer recipes and brewing sessions.

🌟 About the Application

BrewTracker is a full-stack web application that enables homebrewers to:

• Create and manage beer recipes with detailed ingredients and metrics
• Calculate important brewing metrics (OG, FG, ABV, IBU, SRM)
• Track brewing sessions and fermentation progress
• Analyze yeast performance with real-world attenuation data
• Browse and share recipes with advanced search and filtering
• Get AI-powered recipe suggestions for style compliance and optimization
• Share recipes publicly with proper attribution and access control
• View recipe statistics and brewing history

🏗️ Project Structure

This repository contains two applications:

• 🖥️ A frontend React App - User interface for recipe management
• 🔌 A backend Flask API - Python-based server handling recipe calculations and data storage

BrewTracker/
├── backend/
│   ├── app.py                                            # Flask application factory with auto-seeding, CORS, and blueprint registration
│   ├── config.py                                         # Environment-specific configuration classes (development, testing, production)
│   ├── data/                                             # Static JSON data files for ingredients, beer style guides, and system users
│   ├── models/                                           # Database models
│   │   ├── __init__.py
│   │   └── mongo_models.py                               # MongoEngine ODM models with validation, relationships, and business logic
│   ├── routes/                                           # Flask blueprints for API endpoints
│   │   ├── __init__.py
│   │   ├── ai_routes.py                                  # Automated recipe analysis and suggestion generation endpoints
│   │   ├── attenuation_analytics.py                      # Real world yeast attenuation analysis and statistics endpoints
│   │   ├── auth.py                                       # User authentication and authorization endpoints
│   │   ├── beer_styles.py                                # Beer style guide and analysis endpoints
│   │   ├── beerxml.py                                    # BeerXML import/export functionality endpoints
│   │   ├── brew_sessions.py                              # Brew session tracking and fermentation management endpoints
│   │   ├── ingredients.py                                # Ingredient CRUD operations, search endpoints, and yeast attenuation analytics
│   │   ├── recipes.py                                    # Recipe CRUD operations and calculation endpoints
│   │   └── user_settings.py                              # User preferences, account management, and secure account deletion endpoints
│   ├── seeds/                                            # Database seeding scripts
│   │   ├── seed_ingredients.py                           # Seeds ingredients from JSON data
│   │   ├── seed_beer_styles.py                           # Seeds beer style guides from JSON data
│   │   └── seed_system_users.py                          # Seeds system users for account deletion and community features
│   ├── services/                                         # Business logic layer
│   │   ├── __init__.py
│   │   ├── ai/                                           # AI recipe analysis and optimization services
│   │   │   ├── __init__.py                               # Package initialization with clean imports for all AI components
│   │   │   ├── flowchart_ai_service.py                   # Service wrapper for flowchart-based analysis to ensure compatibility with the current frontend expectations
│   │   │   ├── flowchart_engine.py                       # Provides the core engine that performs recipe analysis and optimization using a flowchart-based approach
│   │   │   ├── flowchart_nodes.py                        # Provides the core node types for executing flowchart-based recipe optimization workflows
│   │   │   ├── optimization_strategies.py                # Provides concrete implementations of optimization strategies that can be executed by the FlowchartEngine workflow nodes
│   │   │   ├── recipe_context.py                         # Maintains recipe state throughout workflow execution, handles condition evaluation and strategy execution
│   │   │   ├── workflow_config_loader.py                 # Provides utilities for loading and managing workflow configurations from YAML and JSON files
│   │   │   └── workflows/
│   │   │       ├── AI_flowchart.png                      # Graphical representation of the AI recipe analysis flowchart (showcased in README)
│   │   │       └── recipe_optimization.yaml              # Configuration file for recipe analysis flowchart. Defines all nodes and paths
│   │   ├── attenuation_service.py                        # Service for collecting and analyzing real-world yeast attenuation data
│   │   ├── google_oauth_service.py                       # Google OAuth verification service for BrewTracker
│   │   ├── ingredient_lookup_service.py                  # Provides centralized ingredient search, matching, and substitution logic for the AI optimization system.
│   │   ├── mongodb_service.py                            # Database abstraction layer with connection management and query utilities
│   │   └── user_deletion_service.py                      # Comprehensive user account deletion with data preservation options
│   ├── tests/                                            # pytest test suite for backend functionality
│   ├── utils/                                            # Utility functions and security components
│   │   ├── __init__.py
│   │   ├── brewing_calculation_core.py                   # Pure brewing mathematics (OG, FG, ABV, IBU, SRM calculations) - centralized calculation logic used by all services
│   │   ├── crypto.py                                     # Secure cryptographic utilities for password reset tokens with HMAC-SHA256
│   │   ├── error_handlers.py                             # Centralized error handling with security-conscious information disclosure prevention
│   │   ├── geolocation_service.py                        # Secure HTTPS geolocation service with multiple providers and fallback mechanisms
│   │   ├── input_sanitization.py                         # Multi-layer input sanitization for different data types with XSS protection
│   │   ├── rate_limiter.py                               # Configurable rate limiting framework with Redis support and endpoint-specific limits
│   │   ├── recipe_orm_calculator.py                      # Recipe calculations integrated with MongoDB models and validation
│   │   ├── recipe_api_calculator.py                      # Real-time recipe calculations for API endpoints without database persistence - also used by AI services
│   │   ├── request_validation.py                         # Comprehensive request validation with size limits, field requirements, and security checks
│   │   ├── security_headers.py                           # HTTP security headers (HSTS, CSP, X-Frame-Options, XSS protection, cache control)
│   │   ├── security_monitor.py                           # Real-time security monitoring with brute force detection, audit logging, and alerting
│   │   └── unit_conversions.py                           # Metric/imperial conversion utilities for weight, volume, and temperature
│   ├── requirements.txt                                  # Python package dependencies for backend
│   └── .env                                              # Environment variables for database URI, JWT secrets, and Flask configuration
├── frontend/
│   ├── craco.config.js                                   # CRACO configuration for webpack path alias resolution
│   ├── scripts/
│   │   └── sync-version.js                               # Automated script to sync version constant with package.json
│   ├── public/
│   │   ├── index.html                                    # Main HTML template for React application
│   ├── src/
│   │   ├── components/
│   │   │   ├── BeerXML/                                  # BeerXML import/export components with ingredient matching and validation
│   │   │   ├── BrewSessions/                             # Brew session management with fermentation tracking and progress monitoring
│   │   │   ├── Layout/
│   │   │   │   ├── Footer.tsx                            # A multi-column footer with project links, help resources, and legal information
│   │   │   │   ├── Header.tsx                            # Header component for BrewTracker with the main navigation bar, including logo, navigation links, and user actions
│   │   │   │   └── Layout.tsx                            # Layout component that provides a consistent page structure with a header, main content area, and footer
│   │   │   ├── RecipeBuilder/                            # Complex recipe creation interface with real-time calculations, ingredient management, and AI suggestions
│   │   │   ├── CompactRecipeCard.tsx                     # Unified recipe display component with SRM color swatches, metrics grid, and action filtering
│   │   │   ├── GoogleSignInButton.tsx                    # FedCM-compatible Google Sign-In component with modern authentication support
│   │   │   ├── RecipeActions.tsx                         # Action buttons for recipe operations with public recipe access control (edit, delete, clone, share)
│   │   │   └── SearchableSelect.ts                       # Fuzzy search component with Fuse.js for intelligent ingredient matching and suggestions
│   │   ├── constants/
│   │   │   └── version.ts                                # Application version constant, automatically synchronized with package.json
│   │   ├── contexts/
│   │   │   └── UnitContext.ts                            # React context for global metric/imperial unit preference management
│