Skip to content

README.md

Latest commit

 

History

History
209 lines (147 loc) · 7.43 KB

README.md

File metadata and controls

209 lines (147 loc) · 7.43 KB
Raw

Cambridge Beer Festival App

CI codecov

A Flutter app for browsing beers, ciders, meads, and more at the Cambridge Beer Festival.

Production: https://cambeerfestival.app Staging: https://staging.cambeerfestival.app Development: https://richardthe3rd.github.io/cambridge-beer-festival-app/

Features

  • 🍺 Browse all drinks from the festival (beers, ciders, perry, mead, wine)
  • 🔍 Search by name, brewery, or style
  • 🏷️ Filter by drink category and style
  • ↕️ Sort by name, ABV, brewery, or style
  • 👁️ Hide unavailable drinks (sold out or not yet available)
  • ❤️ Save favorites for easy access
  • ⭐ Rate drinks (1-5 stars)
  • 🏭 View brewery details and all their drinks
  • 📱 Works on Android, iOS, and Web

Screenshots

Coming soon

Getting Started

Prerequisites

  • Flutter SDK (3.38.3 or later)
  • Android Studio, Xcode, or VS Code with Flutter extensions
  • (Optional) mise for automatic tool version management

Installation

# Clone the repository
git clone https://github.com/richardthe3rd/cambridge-beer-festival-app.git
cd cambridge-beer-festival-app

# Option 1: Using mise (recommended)
mise install  # Automatically installs Flutter 3.38.3, Node 21, and other tools
flutter pub get

# Option 2: Manual setup
flutter pub get

# Run the app
flutter run

Development Tasks

If using mise, you can run these convenient tasks:

mise run test      # Run all tests
mise run coverage  # Generate code coverage report
mise run analyze   # Analyze code for issues
mise run dev       # Run app on web (localhost:8080)

Or run them directly:

flutter test                    # Run tests
flutter test --coverage         # Run tests with coverage
flutter analyze --no-fatal-infos # Analyze code
flutter run -d web-server --web-port 8080  # Run on web

Building

# Build for web
flutter build web

# Build for Android
flutter build apk

# Build for iOS
flutter build ios

Project Structure

lib/
├── main.dart              # App entry point
├── models/                # Data models (Drink, Producer, Festival)
├── providers/             # State management (BeerProvider)
├── screens/               # UI screens
│   ├── drinks_screen.dart      # Main drinks list
│   ├── drink_detail_screen.dart # Drink details
│   └── brewery_screen.dart      # Brewery page with drinks
├── services/              # API and storage services
└── widgets/               # Reusable UI components

Testing and Coverage

This project uses multiple testing approaches:

Unit & Widget Tests

Flutter's built-in testing framework with comprehensive test coverage:

# Run all tests
flutter test

# Generate coverage report
flutter test --coverage

# Or using mise
mise run coverage

Code coverage is automatically collected and reported in CI using GitHub's native coverage reporting. Coverage reports are displayed in:

  • Pull request comments showing overall coverage percentage and file-by-file breakdown
  • GitHub Actions job summaries with coverage metrics
  • Commit status checks indicating if coverage meets the 70% threshold

Coverage fails if it drops below 70% overall, helping maintain code quality.

E2E Testing

See ADR 0005 for the rationale behind this approach.

Data API

This app uses the Cambridge Beer Festival data API via a Cloudflare Worker proxy:

  • Base URL: https://data.cambeerfestival.app
  • Example: https://data.cambeerfestival.app/cbf2025/beer.json

Documentation

API documentation and JSON schemas are available in the docs/code/api directory:

Architecture & Documentation

Technical documentation is available in the docs directory - see docs/README.md for a complete overview.

Development & Setup

Testing & Quality

Architecture & Deployment

Additional Resources

Deployment

The app is deployed to multiple environments:

  • Production (Cloudflare Pages): cambeerfestival.app
    • Deployed on version tags (e.g., v2025.12.0)
    • Uses Cloudflare Pages project cambeerfestival, branch release
    • Workflow: .github/workflows/release-web.yml
  • Staging (Cloudflare Pages): staging.cambeerfestival.app
    • Stable staging environment
    • Deployed automatically on push to main
    • Uses Cloudflare Pages project staging-cambeerfestival, branch main
    • Workflow: .github/workflows/ci.yml (deploy-web-preview job)
  • PR Previews (Cloudflare Pages): Unique URL per pull request
    • Each PR gets its own preview environment (e.g., <branch>.staging-cambeerfestival.pages.dev)
    • Preview URL posted as comment on the PR
    • Workflow: .github/workflows/ci.yml (deploy-web-preview job)

Deployment Strategy

  1. Development changes: Push to main → Staging (Cloudflare Pages)
  2. PR reviews: Open PR → Unique Cloudflare Pages preview created
  3. Production releases: Create tag (e.g., v2025.12.0) → Production deployment to cambeerfestival.app

For deployment setup and configuration, see Cloudflare Pages Setup Guide.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Related Projects