doc: Add festival ID to deep linking structure - #186
Merged
richardthe3rd merged 14 commits intoDec 23, 2025
Merged
Conversation
- Document festival-scoped URL structure - Define breadcrumb navigation patterns - Outline implementation phases - List design decisions and open questions
- Category URLs: YES - implement /{festivalId}/category/{name}
- Style URLs: YES - keep and make festival-scoped
- Search URLs: NO - defer for now
- Sort URLs: NO - not needed
- Complete implementation plan with 7 phases - Detailed file-by-file change checklist - Architecture discussion: screen unification options - Recommend composition pattern for shared widgets - Testing strategy and success criteria - Timeline estimate: ~14 hours
- Change all URL paths from /brewery/ to /producer/ - Update parameter names: breweryId → producerId - Update helper function: buildBreweryUrl → buildProducerUrl - Keep BreweryScreen widget name (internal implementation detail) - More accurate: includes wineries, cideries, meaderies, etc. - Add comprehensive testing strategy document Reason: "brewery" is too specific; "producer" is accurate for all beverage producers (breweries, wineries, cideries, meaderies)
- Review all design decisions and documentation - Identify 5 critical considerations needing clarification - Assess risks and propose mitigations - Evaluate implementation readiness (8.5/10) - Provide actionable pre-implementation checklist Key findings: - Design is solid and well-documented - Need to clarify provider-router sync strategy - Need to specify invalid festival handling - Need to document festival switching UX - Overall: Ready to implement with minor clarifications
BREAKING ARCHITECTURAL INSIGHT: Visiting a URL must NOT mutate application state. Key Changes: - Separate 'view festival' (from URL) from 'preferred festival' (user choice) - Provider stores only userPreferredFestival (user's saved default) - Screens read festivalId from URL parameter (read-only) - Bottom nav uses preferred festival (app home) - Breadcrumbs use URL festival (viewing context) - Deep links don't change user's festival preference Impact: - Provider API changes (remove currentFestival, add getFestivalById) - All screens need festivalId parameter - Navigation logic differs for bottom nav vs breadcrumbs - Adds ~2 hours to implementation timeline Benefits: - Correct web standards (URLs are stateless) - Browser history works properly - Deep links don't pollute app state - Clear separation of concerns - More testable and predictable Status: Requires decisions on Q1-Q3 before implementation
Updates: - Add FavoriteItem model supporting multiple "tried" timestamps - Document favorites as festival-scoped to-do lists - Support for "want to try" and "tried" states - Users can mark drinks as tried multiple times - Editable timestamps (go back in time) - Festival summary generation feature - Cloud sync planning for favorites, ratings, and tasting notes - Complete implementation plan (Phase 8) for favorites enhancement Key features: - Map<festivalId, Map<drinkId, FavoriteItem>> storage structure - ISO 8601 timestamps for cloud sync compatibility - Migration strategy from old Set<String> favorites - Conflict resolution for cloud sync (array merging) - UI mockups for to-do list and summary views
User-facing changes:
- Feature name: "Festival Log" (internal), "My Festival" (user-facing)
- Navigation tab: "My Festival"
- Screen title: "My {Festival Name}" (e.g., "My CBF 2025")
- Sections: "To Try" (was "Want to Try") / "Tasted" (was "Tried")
- URL suggestion: /{festivalId}/log or /{festivalId}/my-festival
Code naming (unchanged for now):
- Internal classes remain: FavoriteItem, _favoritesByFestival
- Can rename in implementation phase if desired
Rationale:
- More personal and engaging ("My CBF 2025")
- "Log" better describes tracking function
- "Tasted" more natural than "Tried" for drinks
- Keeps simple UI (no filter/search complexity initially)
Changes:
- Remove section headers ('To Try' / 'Tasted')
- Use single ListView with visual state indicators
- Icon differentiation: circle_outlined (grey) vs check_circle (green)
- Opacity: 100% for to-try, 70% for tasted items
- Quick action: 'Mark as Tasted' button on untasted items
- Move summary button to appbar
User requested simpler UI without sections, this provides
natural visual hierarchy through icons and opacity only.
Changes: - Add visual badge showing log status on drink cards - Three placement options: top-right corner, chip area, or leading icon - Recommend top-right badge (subtle but visible) - Include semantics for screen reader accessibility - Show try count for drinks tasted multiple times This allows users to see their Festival Log status while browsing the Drinks screen, without needing to switch to "My Festival" tab.
Includes: - Press release introducing "My Festival" personal tracker - FAQ covering common user questions - Technical decisions and rationale Key topics: - Multiple tastings with timestamps - Unified list UI with visual indicators - Festival-scoped data isolation - Drinks screen integration - Future cloud sync planning
Match existing docs/ naming convention (UPPERCASE with underscores)
Features: - Prompt for optional notes when marking drink as tasted - Dialog with "Skip" or "Save" options - Pre-fill dialog with existing note when editing - Show notes in drink detail screen (editable card) - Show note preview in festival log list - Festival-scoped storage (separate per festival) - createdAt/updatedAt timestamps for sync UX Flow: 1. User taps "Mark as Tasted" 2. Dialog appears: "How was it? (optional)" 3. User can skip or enter notes 4. Notes editable anytime from detail or log screen 5. Empty note = delete note Benefits: - Immediate capture while impressions are fresh - Optional (no friction if user is busy) - Editable and refinable later - Ready for cloud sync
Changes: - Rename _markAsTasted → _addTasting (clearer intent) - Add "Undo" action in snackbar for immediate mistakes - FAB button changes: "Mark as Tasted" → "Add Another" - Show numbered tasting history (1, 2, 3...) - Swipe to delete individual tastings (for mistakes) - Confirmation only if drink has multiple tastings - Edit timestamps via tap (for corrections) - Notes are per-drink, not per-tasting Key UX principle: Adding tastings is primary action (additive), deletion is available but de-emphasized (for mistakes only). Multiple tastings are normal festival behavior.
richardthe3rd
marked this pull request as ready for review
December 23, 2025 20:35
richardthe3rd
changed the title
richardthe3rd
deleted the
claude/add-festival-deep-linking-019Y2X9U5o5MNup74B4Gj1qx
branch
December 23, 2025 21:04
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request adds two new documentation files that outline major new features and architectural changes for the Cambridge Beer Festival app. The first document details the new "My Festival" personal tracker (Festival Log) feature, while the second provides a comprehensive design for festival-scoped deep linking and navigation. These documents clarify both user-facing functionality and technical decisions, setting a clear roadmap for upcoming development.
Feature Documentation: Festival Log ("My Festival")
Technical Architecture: Deep Linking and Navigation