🍸 StirCraft: Cocktail Recipe Manager

Your Personal Mixology Companion - Now Live!
🌐 Try StirCraft Live

🚀 Live Demo Available

StirCraft is live and ready to use!

🌐 Live App: https://stircraft-app-0dd06cf5d30a.herokuapp.com/
👨‍💼 Admin Panel: https://stircraft-app-0dd06cf5d30a.herokuapp.com/admin/
📊 Database: 416+ cocktails, 325+ ingredients, 15 vessel types, ready to explore

🎯 What is StirCraft?

StirCraft is a comprehensive cocktail recipe management application that empowers mixology enthusiasts to discover, create, and organize their favorite cocktail recipes. Whether you're a professional bartender or a home cocktail enthusiast, StirCraft provides the tools you need to build your personal cocktail library.

💡 The Problem We Solve

Cocktail enthusiasts face scattered recipe sources, inconsistent measurements, and no way to organize their growing collection of favorites. StirCraft centralizes everything in one elegant, user-friendly platform.

🎯 Our Solution

A complete cocktail management ecosystem featuring:

Discovery: 400+ professionally curated cocktails
Creation: Custom recipe builder with smart ingredients
Organization: Personal lists, favorites, and collections
Community: Share and discover recipes with fellow mixologists

✨ Key Features & Demo

🔐 User Authentication & Profiles

✅ Secure user registration and login
✅ Personalized user profiles with location and preferences
✅ Age verification (21+) for responsible service
Try Registration →

🍹 Comprehensive Cocktail Management

✅ Discover: Browse 416+ cocktails including classics like Martini, Margarita, Old Fashioned
✅ Create: Build custom cocktail recipes with detailed ingredients
✅ Edit: Modify and perfect your recipes
✅ Organize: Add cocktails to custom lists and favorites
Explore Cocktails →

📋 Smart List Management

✅ Favorites: One-click favoriting system
✅ Your Creations: Automatic collection of user-created recipes
✅ Custom Lists: Create themed collections (e.g., "Summer Cocktails", "Party Drinks")
✅ Quick Actions: Easy add/remove functionality
View Dashboard →

🥃 Ingredient & Vessel Database

✅ Extensive ingredient catalog with 325+ ingredients
✅ Alcohol content tracking and calculations
✅ 15 vessel types with proper glassware recommendations
✅ Smart measurement conversion
Browse Ingredients →

🎨 Modern, Responsive Design

✅ Clean, professional interface built with Bootstrap
✅ Mobile-responsive design for on-the-go access
✅ Intuitive navigation and user experience
✅ Accessibility-compliant design

🏆 Technical Excellence

🆕 Recent Improvements (August 2025)

✅ Color Filtering System: Visual color filter buttons with database-matched values
✅ Vibe Detection AI: Intelligent cocktail categorization with 40+ vibe types (tropical, winter, party, etc.)
✅ JavaScript Optimization: Resolved favorites button conflicts and improved error handling
✅ Enhanced Testing: 245+ Django tests + 23+ JavaScript tests with 100% critical path coverage
✅ Advanced Search: Multi-field filtering with real-time updates and progressive enhancement

📊 Production Stats

✅ 245/245 Python Tests + 23/23 JavaScript Tests Passing (100% test coverage on critical functionality)
✅ Live Deployment on Heroku with PostgreSQL (v17)
✅ Security Headers and HTTPS enabled
✅ Performance Optimized with static file compression and image processing

🛠 Tech Stack

Backend: Django 5.2.5, Python 3.13
Database: PostgreSQL with 416+ cocktails, 325+ ingredients, 15 vessel types
Frontend: Bootstrap 5, Responsive HTML/CSS/JS
Deployment: Heroku with WhiteNoise for static files
APIs: TheCocktailDB integration for cocktail data

🎯 Ready to Start Mixing?

🚀 Try It Now - No Installation Required!

🌐 Launch StirCraft

Sign Up - Create your free account
Explore - Browse 416+ cocktails including classics
Create - Build your own recipes
Organize - Manage your collections

🏠 Local Development Setup

Try StirCraft

👉 Visit StirCraft Live Application (Coming Soon)

Explore the Code

📋 View Planning Materials - Project roadmap and current status
💻 GitHub Repository - Full source code
📚 Technical Documentation - Developer setup guide

🛠️ Technologies Used

Backend

Python 3.12 - Core programming language
Django 5.2.5 - Web framework for rapid development
PostgreSQL - Robust database for data persistence
Django REST Framework - API development (future enhancement)

Frontend

HTML5 & CSS3 - Modern web standards
Bootstrap 5 - Responsive design framework
Django Templates - Server-side rendering
JavaScript - Interactive user experiences

External Integrations

TheCocktailDB API - Cocktail recipe data source
django-taggit - Flexible tagging system
Redis - Caching and session management

Deployment & DevOps

Heroku - Cloud application hosting
Gunicorn - Production WSGI server
WhiteNoise - Static file serving
PostgreSQL - Production database

🎯 Next Steps: Planned Enhancements

User Experience

Recipe Ratings & Reviews - Community-driven quality feedback
Advanced Search - Filter by ingredients, difficulty, time to make
Recipe Recommendations - AI-powered suggestions based on preferences
Social Features - Follow other users and share recipe collections

Technical Enhancements

Mobile App - Native iOS and Android applications
Recipe Import/Export - Import from popular cocktail apps and websites
Inventory Tracking - Track your home bar ingredients
Shopping Lists - Generate ingredient shopping lists for recipes

Community Features

Recipe Comments - Discussion and tips on recipes
Photo Uploads - Share photos of your cocktail creations
Recipe Contests - Monthly themed cocktail competitions
Expert Profiles - Verified bartender and mixologist accounts

🏆 Project Attributions

External Resources

TheCocktailDB - Comprehensive cocktail recipe database
Bootstrap - CSS framework for responsive design
Django - High-level Python web framework
Icons from Font Awesome - Professional iconography

Team

General Assembly Team 1 - Full-stack development team specializing in Django web applications

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🍸 Ready to mix things up? Start exploring StirCraft today!

Built with ❤️ by cocktail enthusiasts, for cocktail enthusiasts

🎨 Frontend Styling: Bootstrap

This project uses Bootstrap for frontend styling. Bootstrap provides CSS classes (e.g., card-header, btn, etc.) used throughout our templates.

How to Enable Bootstrap

Recommended (CDN): Add the following line to the <head> section of your base.html template:

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">

This loads Bootstrap from the web. No installation is required.

Optional (Local Install): If you prefer to use a local copy, you can download Bootstrap or install it via npm:

npm install bootstrap

Then link to the CSS file in your static files setup. See the Bootstrap docs for details.

Why Bootstrap?

Bootstrap makes it easy to create responsive, modern layouts and UI components. All team members should ensure Bootstrap is enabled to see the intended styles.

🎯 MVP Goals

Core Features

User authentication (Sign Up / Sign In)
Dashboard with editable profile, user-created lists, and recipes
Ingredient and vessel management with reusable forms
Recipe creation with dynamic ingredient and vessel selection
Recipe catalog with filtering by vibe, flavor tags, and color
Error handling views for bad paths, restricted access, and failed requests

Technical Stack

Backend: Django 5.2.5 + PostgreSQL
API Integration: TheCocktailDB API for real cocktail data
Data Processing: Intelligent ingredient categorization and measurement parsing
Frontend: Django templates with Bootstrap CSS
Tagging: django-taggit for flavor profiles
Testing: Django's built-in test framework
Version Control: Git + GitHub

✅ Wireframes Completed

✅ Models & Testing

Ingredient model uses django-taggit for flavor tags
Model tests scaffolded for Ingredient, Recipe, and List
Sample test for Ingredient.flavor_tags using TaggableManager
Plan to modularize form logic for reuse across views

✅ Cocktail Forms & Views (NEW!)

Advanced Form System: Complete cocktail creation with inline formsets for multiple ingredients
Dynamic Ingredient Management: Add/remove ingredients with proper Django formset validation
Pure Django Solution: No JavaScript required - leverages Django's built-in formset capabilities
Comprehensive Views: Create, list, detail, and search functionality for cocktails
Professional Templates: Bootstrap-styled forms with proper error handling and user feedback
Search & Filter: Advanced cocktail filtering by ingredients, vessel type, alcohol content, and more

✅ Git Workflow

Shell script created to update all local branches from remote (origin)
Testing strategy outlined using Django’s TestCase, setUpTestData, and assertions

🎯 MVP Goals

Core Features

User authentication (Sign Up / Sign In)
Dashboard with editable profile, user-created lists, and recipes
Ingredient and vessel management with reusable forms
Recipe creation with dynamic ingredient and vessel selection
Recipe catalog with filtering by vibe, flavor tags, and color
Error handling views for bad paths, restricted access, and failed requests

Technical Stack

Backend: Django + Postgres
Frontend: Django templates with vanilla CSS
Tagging: django-taggit for flavor profiles
Testing: Django’s built-in test framework
Version Control: Git + GitHub

✨ Stretch Goals

UX & Features

Social login (Google, GitHub)
Recipe remixing and forking
Ingredient detail pages with usage stats
Color picker or auto-detection for cocktail color
Vibe-based sorting (e.g., “Cozy,” “Tropical,” “Party”)
User badges or achievements (e.g., “Citrus Connoisseur”)

Technical Enhancements

API endpoints for recipes, ingredients, and lists
Responsive design with mobile-first layout
Inline form validation and error messaging
Admin dashboard for moderation or featured recipes
CI/CD pipeline with test coverage tracking

🍸 Cocktail Forms System (NEW!)

Overview

StirCraft now includes a comprehensive cocktail creation and management system using Django's inline formsets. This allows users to create complex cocktail recipes with multiple ingredients, measurements, and preparation notes in a single, intuitive form.

Key Components

Forms (`cocktail_forms.py`)

CocktailForm: Main cocktail information (name, description, instructions, vessel, tags)
RecipeComponentForm: Individual ingredient with amount, unit, and preparation notes
RecipeComponentFormSet: Manages multiple ingredients using Django's inlineformset_factory
QuickIngredientForm: For adding new ingredients on-the-fly (future modal integration)
CocktailSearchForm: Advanced search and filtering for cocktail browsing

Views

cocktail_create: Handles formset creation with proper validation and error handling
cocktail_index: Browse cocktails with search, filter, and pagination
cocktail_detail: Full recipe display with stats, ingredient details, and user actions

Templates

cocktail_create.html: Rich form interface with dynamic ingredient management
cocktail_index.html: Responsive cocktail browsing with search filters
cocktail_detail.html: Complete recipe display with nutritional info and actions

Features

Dynamic Form Management

Django formset handles multiple ingredients seamlessly
Automatic form validation for required fields
Smart alcohol content calculation based on ingredients
Order management for ingredient addition sequence

Advanced Validation

Minimum 1 ingredient required per cocktail
Maximum 15 ingredients to prevent abuse
Proper unit validation with predefined choices
Age verification integration for alcoholic beverages

User Experience

Bootstrap-styled responsive forms
Clear error messaging and field validation
Helpful tips and user guidance
Mobile-optimized form layouts

Search & Filter Capabilities

Text search across cocktail names and descriptions
Filter by specific ingredients or vessel types
Alcoholic/non-alcoholic filtering
Color-based filtering
Sort by creation date, name, or creator

Usage Examples

Creating a Cocktail

# In views.py - the formset handles both cocktail and ingredients
cocktail_form = CocktailForm(user=request.user)
formset = RecipeComponentFormSet()

# Form validates both main cocktail and all ingredients
if cocktail_form.is_valid() and formset.is_valid():
    cocktail = cocktail_form.save(commit=False)
    cocktail.creator = request.user
    cocktail.save()
    
    formset.instance = cocktail
    components = formset.save()

Template Integration

<!-- cocktail_create.html -->
{{ formset.management_form }}
{% for form in formset %}
    <div class="ingredient-row">
        {{ form.ingredient }}
        {{ form.amount }} {{ form.unit }}
        {{ form.preparation_note }}
    </div>
{% endfor %}

URLs Added

/cocktails/ - Browse all cocktails
/cocktails/create/ - Create new cocktail
/cocktails/<id>/ - View cocktail details

Technical Implementation Notes

Why Inline Formsets?

Perfect Model Match: Your RecipeComponent join table is designed exactly for this pattern
Clean Data Structure: Each ingredient has precise amount, unit, and preparation notes
Django-Native: Uses built-in inlineformset_factory - no custom JavaScript required initially
Scalable: Easy to enhance with AJAX and dynamic features later

Performance Optimizations

Uses select_related() and prefetch_related() for efficient queries
Pagination for large cocktail lists
Indexed database fields for fast searching
Minimal template queries with optimized context

Future Enhancements

AJAX Integration: Add ingredients without page refresh
Auto-suggestions: Typeahead for ingredient selection
Recipe Import: Bulk import from cocktail APIs
Image Uploads: Add cocktail photos
Advanced Validation: Ingredient compatibility checking

StirCraft evokes creativity, modularity, and flavor exploration
Wireframes and UI lean into playful but clean design
Flavor tags and vibe filters support expressive, user-driven discovery

🛠️ Setup Instructions

Prerequisites

Python 3.12+
PostgreSQL
Git

🔐 Environment Variables Setup (NEW!)

IMPORTANT: This project now uses secure environment variables for all secrets. Follow these steps carefully:

Copy the environment template:
```
cp .env.example .env
```

Generate a new secret key:

pipenv run python -c "from django.core.management.utils import get_random_secret_key; print('SECRET_KEY=' + get_random_secret_key())"

Edit your .env file:

# Edit .env and replace the SECRET_KEY with the generated one
# Update your database password if different from the default

NEVER commit .env files:
- Your .env file contains secrets and is automatically ignored by git
- Always use .env.example as a template for new environments
- For production, use your platform's secret management (GitHub Actions secrets, AWS Parameter Store, etc.)

Database Setup

Install and start PostgreSQL:

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql

# macOS with Homebrew
brew install postgresql
brew services start postgresql

Create database and user:

sudo -u postgres createuser --interactive --pwprompt macfarley
# Enter a secure password when prompted (update your .env file with this password)

sudo -u postgres createdb --owner=macfarley stircraft

Update your .env file:

# Edit .env and set your actual database password
DATABASE_URL=postgres://macfarley:your-actual-password@localhost:5432/stircraft

Application Setup

Clone the repository:

git clone https://github.com/General-Assembly-Team-1/stir-craft.git

Navigate to the project directory:
```
cd stir-craft
```

Copy environment template:

cp .env.example .env
# Then edit .env with your actual values (see above)

Install dependencies:
```
pipenv install
```
Activate the virtual environment:
```
pipenv shell
```
Navigate to the Django project:
```
cd stircraft
```

Apply database migrations:

# No need to export DB_PASSWORD - it's now read from .env automatically
python manage.py migrate

Seed the database with cocktail data:

# Import a small test batch (10 cocktails)  
python manage.py seed_from_thecocktaildb --limit 10

# Import 100 cocktails from all letters
python manage.py seed_from_thecocktaildb --limit 100

# Import ALL available cocktails (could be 500+)
python manage.py seed_from_thecocktaildb

Create a superuser:
```
python manage.py createsuperuser
```
Run the development server:
```
python manage.py runserver
```
Access the application:
- Main application: http://127.0.0.1:8000/
- Admin interface: http://127.0.0.1:8000/admin/

🔒 Security Notes

For Development

Always use .env.example as your template
Generate a unique SECRET_KEY for your local environment
Never commit your .env file to version control
Use secure database passwords (not the ones shown in documentation)

For Production

Use your platform's secret management system:
- GitHub Actions: Repository secrets (Settings → Secrets and variables → Actions)
- Heroku: Config vars (Settings → Config Vars)
- AWS: Parameter Store or Secrets Manager
- Docker: Environment variables or secret mounts
Set DEBUG=False in production
Use strong, unique passwords for all services
Configure proper ALLOWED_HOSTS for your domain

For Team Collaboration

Each team member should create their own .env file
Share configuration requirements via .env.example
Document any new environment variables in .env.example
Use different database passwords for each developer

📊 Data Management

Cocktail Data Seeding

The project includes a comprehensive management command to populate the database with real cocktail data from TheCocktailDB API:

# Basic usage - import 10 cocktails for testing
python manage.py seed_from_thecocktaildb --limit 10

# Import specific number of cocktails
python manage.py seed_from_thecocktaildb --limit 50

# Import from specific letters only
python manage.py seed_from_thecocktaildb --letters abc --limit 20

# Import ALL available cocktails (500+)
python manage.py seed_from_thecocktaildb

# Clear existing data and start fresh
python manage.py seed_from_thecocktaildb --clear --limit 25

What Gets Imported

Cocktails: Name, instructions, image URLs, categories
Ingredients: Automatically categorized (spirits, liqueurs, mixers, etc.) with alcohol content estimation
Vessels: Glassware types matched to StirCraft's vessel system
Recipe Components: Measurements parsed from text to structured data
Flavor Tags: Intelligent tagging for advanced filtering

Data Processing Features

Smart Categorization: Ingredients are automatically categorized as spirits, liqueurs, mixers, etc.
Measurement Parsing: Text measurements like "1 oz" or "2 dashes" are converted to structured data
Alcohol Content: Estimated alcohol percentages for ingredients
Duplicate Prevention: Uses get_or_create() to avoid duplicate entries
Error Handling: Robust error recovery and detailed logging

🌟 Join the StirCraft Community

🚀 Start Your Mixology Journey Today

🌐 Visit StirCraft Live

Whether you're a professional bartender, cocktail enthusiast, or just starting your mixology journey, StirCraft provides everything you need to discover, create, and organize amazing cocktail recipes.

📞 Connect & Contribute

🐛 Report Issues: Found a bug? We want to fix it!
💡 Feature Ideas: Have a suggestion? We'd love to hear it!
🤝 Contribute: This is an open-source project welcoming contributions
📧 Contact: Reach out for collaboration opportunities

🏆 Built with Excellence

StirCraft represents modern web development best practices:

✅ Test-Driven Development (245 Python + 23 JavaScript tests passing)
✅ Responsive Design (Mobile-first approach)
✅ Security-First (Production-ready security headers)
✅ Performance Optimized (Static file compression, efficient queries)
✅ Accessible (WCAG compliant design)

🍸 Crafted with passion for the art of mixology
Made with Django 5.2.5 • Bootstrap 5 • PostgreSQL • Love

Start Mixing Now →

🧠 Contribution Guidelines

Create a personal branch:
```
git checkout -b <your-branch-name>
```

Commit changes to your branch:

git add .
git commit -m "Your commit message"

Push your branch:
```
git push origin <your-branch-name>
```
Open a pull request for review.

📚 Documentation

For detailed technical documentation, development guides, and project history, see the docs/ folder:

Development Guide - Setup, workflow, and contribution guidelines
Cocktail Forms Technical Guide - Complete technical documentation for the forms system
Project Changelog - Detailed development history and milestones

For questions or support, please refer to the documentation or contact the development team.

Name		Name	Last commit message	Last commit date
Latest commit History 163 Commits
.github/workflows		.github/workflows
bin		bin
deployment		deployment
docs		docs
scripts		scripts
stircraft		stircraft
tests		tests
.env.example		.env.example
.env.prod.example		.env.prod.example
.env.test		.env.test
.gitignore		.gitignore
DEV-SETUP-README.md		DEV-SETUP-README.md
LICENSE		LICENSE
Pipfile		Pipfile
Pipfile.lock		Pipfile.lock
Procfile		Procfile
README.md		README.md
TEST-RESULTS-REPORT.md		TEST-RESULTS-REPORT.md
TEST_REORGANIZATION_SUMMARY.md		TEST_REORGANIZATION_SUMMARY.md
dev-setup-check.sh		dev-setup-check.sh
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
quick-fix.sh		quick-fix.sh
requirements.txt		requirements.txt
test_form_layout.html		test_form_layout.html

Folders and files

Latest commit

History

Repository files navigation

🍸 StirCraft: Cocktail Recipe Manager

🚀 Live Demo Available

🎯 What is StirCraft?

💡 The Problem We Solve

🎯 Our Solution

✨ Key Features & Demo

🔐 User Authentication & Profiles

🍹 Comprehensive Cocktail Management

📋 Smart List Management

🥃 Ingredient & Vessel Database

🎨 Modern, Responsive Design

🏆 Technical Excellence

🆕 Recent Improvements (August 2025)

📊 Production Stats

🛠 Tech Stack

🎯 Ready to Start Mixing?

🚀 Try It Now - No Installation Required!

🏠 Local Development Setup

Try StirCraft

Explore the Code

🛠️ Technologies Used

Backend

Frontend

External Integrations

Deployment & DevOps

🎯 Next Steps: Planned Enhancements

User Experience

Technical Enhancements

Community Features

🏆 Project Attributions

External Resources

Team

📄 License

🍸 Ready to mix things up? Start exploring StirCraft today!

🎨 Frontend Styling: Bootstrap

How to Enable Bootstrap

Why Bootstrap?

🎯 MVP Goals

Core Features

Technical Stack

✅ Wireframes Completed

✅ Models & Testing

✅ Cocktail Forms & Views (NEW!)

✅ Git Workflow

🎯 MVP Goals

Core Features

Technical Stack

✨ Stretch Goals

UX & Features

Technical Enhancements

🍸 Cocktail Forms System (NEW!)

Overview

Key Components

Forms (cocktail_forms.py)

Views

Templates

Features

Dynamic Form Management

Advanced Validation

User Experience

Search & Filter Capabilities

Usage Examples

Creating a Cocktail

Template Integration

URLs Added

Technical Implementation Notes

Why Inline Formsets?

Performance Optimizations

Future Enhancements

🛠️ Setup Instructions

Prerequisites

🔐 Environment Variables Setup (NEW!)

Database Setup

Application Setup

🔒 Security Notes

For Development

Forms (`cocktail_forms.py`)

Packages