Organized documentation for the Cambridge Beer Festival app.
How the codebase works -- implementation guides, architecture, and technical references.
- accessibility.md - Accessibility implementation (WCAG 2.1 Level AA)
- domain-architecture.md - Domain layer architecture (filter/sort services, repositories)
- routing.md - URL routing (path-based with GoRouter)
- navigation.md - Navigation helper API reference
- widget-standards.md - Widget patterns and standards
- ui-components.md - Shared UI components (OverflowMenu, BreadcrumbBar)
- network.md - Network security configuration and allowlist
- api/ - API documentation
- README.md - API overview
- data-api-reference.md - Complete API reference
- beer-list-schema.json - JSON Schema for beverage data
- festival-registry-schema.json - JSON Schema for festival config
Key decisions with context, alternatives considered, and consequences.
- 0001 - GitHub Actions Caching Strategy
- 0002 - Composite Actions and Test Deduplication
- 0003 - Parallel Build Strategy for Android Releases
- 0004 - Path-Based URL Strategy for Deep Linking
- 0005 - E2E Testing Strategy (Playwright for URL smoke tests)
- development.md - Development workflow and best practices
- ci-cd.md - CI/CD workflows and pipeline
- festival-data-prs.md - FAQ for handling festival data pull requests
- safe-cache-strategy.md - What to cache (and avoid) in GitHub Actions
- android-debug.md - Android debug build configuration
- android-release.md - Android release build process
- firebase.md - Firebase setup and configuration
- cloudflare-pages.md - Cloudflare Pages deployment setup
- github-secrets.md - GitHub secrets management
- flutter-web-testing.md - Flutter web testing (Playwright E2E)
- play-store.md - Play Store metadata and publishing
- festival-log/ - Festival tasting log feature (proposal, not yet implemented)
- ux-improvements.md - UX enhancements (8 of 30 implemented, 7 more recommended)
Completed or superseded planning documents retained for context:
- archive/deep-linking/ - Deep linking design, implementation plans, and reviews (Phase 1 complete, decisions captured in ADR 0004)
- archive/patrol-firebase-testing/ - Patrol + Firebase Test Lab evaluation (not implemented, decision captured in ADR 0005)
- archive/ci-review/ - CI/CD review and optimisations (implemented, decisions captured in ADRs 0001-0003)
- todos.md - Active TODO list with bugs, improvements, and project status
Understand the codebase:
- How accessibility works → code/accessibility.md
- How routing works → code/routing.md
- How the API works → code/api/data-api-reference.md
- Navigation helpers → code/navigation.md
- Shared UI components → code/ui-components.md
Understand a past decision:
- Why path-based URLs? → ADR 0004
- Why Playwright for E2E? → ADR 0005
- Why cache pub/npm but not build artifacts? → ADR 0001
Set up development tools:
- Android builds → tooling/android-debug.md or tooling/android-release.md
- Firebase → tooling/firebase.md
- E2E testing → tooling/flutter-web-testing.md
- Cloudflare deployment → tooling/cloudflare-pages.md
Follow a process:
- Contribute code → processes/development.md
- Understand CI/CD → processes/ci-cd.md
- Handle festival data PRs → processes/festival-data-prs.md
Plan future work:
- Festival log feature → planning/festival-log/design.md
- UX improvements → planning/ux-improvements.md
- Bugs and TODOs → todos.md
-
Choose the right category:
- Documenting existing code? →
code/ - Recording a decision? →
adr/(use next sequential number) - Describing a process? →
processes/ - Writing a setup guide? →
tooling/ - Proposing future work? →
planning/
- Documenting existing code? →
-
Use clear, descriptive filenames (lowercase, kebab-case)
-
Update this README when adding new documents
-
Completed planning docs should be archived to
planning/archive/with decisions extracted into ADRs
- ../CLAUDE.md - Instructions for Claude AI
- ../AGENTS.md - Guide for AI agents
- ../README.md - Project overview
Last Updated: February 2026