Skip to content

README.md

Latest commit

 

History

History
204 lines (144 loc) · 9.04 KB

README.md

File metadata and controls

204 lines (144 loc) · 9.04 KB
Raw

Cambridge Beer Festival App

CI PR Lint codecov Flutter Platforms GitHub release License: MIT Play Store

A Flutter app for browsing, searching, and rating the beers, ciders, perries, meads, and wines on offer at the Cambridge Beer Festival — on Android, iOS, and the web.

Built for real festival conditions: the drinks list is cached so it keeps working when the venue network drops, and every screen is built with screen-reader semantics and keyboard/touch accessibility in mind.

Production: cambeerfestival.app Staging: staging.cambeerfestival.app Android: Google Play API docs: richardthe3rd.github.io/cambridge-beer-festival-app

Features

  • 🍺 Browse all drinks from the festival (beer, cider, perry, mead, wine, and more)
  • 🔍 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)
  • 📋 Build your My Festival list — mark drinks "Want to try", then "Tasted"
  • ⭐ Rate drinks (1–5 stars) and jot personal tasting notes
  • 🏭 View brewery details and all their drinks
  • ♿ Accessibility-first: screen-reader semantics on every interactive element
  • 📶 Cached data keeps browsing usable when the festival network is patchy
  • 📱 Works on Android, iOS, and Web

Screenshots

Screenshots coming soon — try the live app at cambeerfestival.app.

Getting Started

Prerequisites

  • Flutter SDK 3.44.0 — pinned and installed for you by ./bin/mise (the repo ships this wrapper, so a global mise install is optional)
  • Android Studio, Xcode, or VS Code with Flutter extensions

Installation

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

# Install tools (Flutter 3.44.0, Node, etc.) — ./bin/mise self-bootstraps,
# so you don't need mise installed globally
./bin/mise install

# Install Dart dependencies and verify setup
./bin/mise run check

# Run the app on web
MISE_ENV=dev ./bin/mise run dev

Development Tasks

./bin/mise run test             # Run all tests
./bin/mise run coverage         # Run tests with coverage report
./bin/mise run analyze          # Analyze code for issues
./bin/mise run check            # Full pre-commit gate (generate → analyze → test)
MISE_ENV=dev ./bin/mise run dev # Run app on web (localhost:8080)

Building

# Build for web
MISE_ENV=dev ./bin/mise run build:web:prod

# Build for Android
./bin/mise exec flutter -- flutter build apk

# Build for iOS
./bin/mise exec flutter -- 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:

./bin/mise run test      # Run all tests
./bin/mise run coverage  # Run tests with coverage report

Coverage is collected in CI and reported in two places:

  • PR comments and job summaries — file-by-file breakdown via github-actions-report-lcov
  • Codecov — trend tracking and the badge above

Coverage fails CI if it drops below 70%.

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

Trigger Lands on
Push to main Staging — staging.cambeerfestival.app
Open a pull request A unique per-PR preview (<branch>.staging-cambeerfestival.pages.dev), posted as a comment on the PR
Push a version tag (e.g. v2025.12.0) Production — cambeerfestival.app

The app is hosted on Cloudflare Pages, with the API served by a Cloudflare Worker. For the full detail — every workflow, the Pages projects, and the release train:

Contributing

Contributions are welcome! Before opening a pull request, please read:

  • Development Guide — setup, workflows, and conventions
  • AGENTS.md — architecture, code style, testing, and accessibility standards (written for AI agents, but the rules apply to everyone)

Run ./bin/mise run check (generate → analyze → test) before every commit, and follow Conventional Commits for commit and PR titles.

License

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

Related Projects