5c75b935f0
Add comprehensive project documentation and Docker infrastructure for Paper Dynasty Real-Time Game Engine - a web-based multiplayer baseball simulation platform replacing the legacy Google Sheets system. Documentation Added: - Complete PRD (Product Requirements Document) - Project README with dual development workflows - Implementation guide with 5-phase roadmap - Architecture docs (backend, frontend, database, WebSocket) - CLAUDE.md context files for each major directory Infrastructure Added: - Root docker-compose.yml for full stack orchestration - Dockerfiles for backend and both frontends (multi-stage builds) - .dockerignore files for optimal build context - .env.example with all required configuration - Updated .gitignore for Python, Node, Nuxt, and Docker Project Structure: - backend/ - FastAPI + Socket.io game engine (Python 3.11+) - frontend-sba/ - SBA League Nuxt 3 frontend - frontend-pd/ - PD League Nuxt 3 frontend - .claude/implementation/ - Detailed implementation guides Supports two development workflows: 1. Local dev (recommended): Services run natively with hot-reload 2. Full Docker: One-command stack orchestration for testing/demos Next: Phase 1 implementation (backend/frontend foundations)
254 lines
6.5 KiB
Markdown
254 lines
6.5 KiB
Markdown
# Phase 4: Spectator Mode & Polish
|
|
|
|
**Duration**: Weeks 10-11
|
|
**Status**: Not Started
|
|
**Prerequisites**: Phase 3 Complete
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Implement spectator mode for real-time game viewing, add UI/UX polish including animations, optimize mobile touch experience, and improve accessibility. Focus on production-ready user experience.
|
|
|
|
## Key Objectives
|
|
|
|
By end of Phase 4, you should have:
|
|
- ✅ Spectator mode fully functional
|
|
- ✅ Dice roll animations working
|
|
- ✅ Smooth transitions and loading states
|
|
- ✅ Mobile touch optimization
|
|
- ✅ Accessibility improvements (WCAG 2.1 AA)
|
|
- ✅ Error handling and recovery UX
|
|
- ✅ Performance optimizations
|
|
- ✅ Production-ready polish
|
|
|
|
## Major Components to Implement
|
|
|
|
### 1. Spectator Mode
|
|
|
|
**Backend**:
|
|
- Spectator WebSocket events (read-only)
|
|
- Spectator room management
|
|
- Spectator count tracking
|
|
- Permission enforcement
|
|
|
|
**Frontend**:
|
|
- Spectator-specific game view
|
|
- Read-only interface (no decision prompts)
|
|
- Spectator count display
|
|
- Join spectator link generation
|
|
- Late join to active games
|
|
|
|
### 2. Animations & Transitions
|
|
|
|
**Dice Roll Animation**:
|
|
- 3D dice roll effect or 2D animation
|
|
- Suspenseful timing (1-2 seconds)
|
|
- Synchronized across all clients
|
|
- Sound effects (optional)
|
|
|
|
**Play Outcome Transitions**:
|
|
- Runner movement animations
|
|
- Score change animations
|
|
- Smooth state transitions
|
|
- Visual feedback for key moments
|
|
|
|
**UI Transitions**:
|
|
- Page transitions
|
|
- Modal animations
|
|
- Accordion collapse/expand
|
|
- Loading skeletons
|
|
|
|
### 3. Mobile Touch Optimization
|
|
|
|
**Touch Interactions**:
|
|
- Swipe gestures (navigate play history)
|
|
- Pull to refresh
|
|
- Tap feedback (haptic if supported)
|
|
- Touch target sizing (44x44px minimum)
|
|
|
|
**Layout Refinements**:
|
|
- Safe area handling (iOS notch)
|
|
- Keyboard avoidance
|
|
- Scroll behavior optimization
|
|
- Bottom sheet interactions
|
|
|
|
**Performance**:
|
|
- Lazy loading images
|
|
- Virtual scrolling for long lists
|
|
- Debounced scroll handlers
|
|
- Optimized re-renders
|
|
|
|
### 4. Accessibility Improvements
|
|
|
|
**Screen Reader Support**:
|
|
- Semantic HTML elements
|
|
- ARIA labels on interactive elements
|
|
- Announcements for game events
|
|
- Focus management in modals
|
|
|
|
**Keyboard Navigation**:
|
|
- Tab order optimization
|
|
- Keyboard shortcuts for actions
|
|
- Focus indicators
|
|
- Escape key handling
|
|
|
|
**Visual Accessibility**:
|
|
- Color contrast validation (4.5:1 minimum)
|
|
- Focus indicators
|
|
- Text sizing options
|
|
- Reduced motion support
|
|
|
|
**Accessible Notifications**:
|
|
- Screen reader announcements for plays
|
|
- Visual + auditory feedback options
|
|
- Status updates in accessible format
|
|
|
|
### 5. Error Handling & Recovery
|
|
|
|
**Connection Issues**:
|
|
- Graceful offline mode
|
|
- Reconnection feedback
|
|
- Action queue during disconnect
|
|
- State sync on reconnect
|
|
|
|
**Error States**:
|
|
- Friendly error messages
|
|
- Recovery actions provided
|
|
- Error boundaries (prevent crashes)
|
|
- Fallback UI
|
|
|
|
**Loading States**:
|
|
- Loading skeletons
|
|
- Progress indicators
|
|
- Timeout handling
|
|
- Cancel operations
|
|
|
|
### 6. Performance Optimizations
|
|
|
|
**Frontend**:
|
|
- Code splitting by route
|
|
- Component lazy loading
|
|
- Image optimization (WebP, lazy load)
|
|
- Bundle size reduction
|
|
- Memoization of expensive computations
|
|
|
|
**Backend**:
|
|
- Response caching
|
|
- Database query optimization
|
|
- Connection pool tuning
|
|
- Memory usage monitoring
|
|
|
|
**WebSocket**:
|
|
- Message compression
|
|
- Batch updates where possible
|
|
- Efficient state diff broadcasts
|
|
|
|
## Implementation Order
|
|
|
|
1. **Week 10**: Spectator Mode + Animations
|
|
- Spectator WebSocket events
|
|
- Read-only game view
|
|
- Dice roll animation
|
|
- Play outcome transitions
|
|
|
|
2. **Week 11**: Polish + Accessibility + Performance
|
|
- Mobile touch optimization
|
|
- Accessibility audit and fixes
|
|
- Error handling improvements
|
|
- Performance profiling and optimization
|
|
|
|
## Testing Strategy
|
|
|
|
### Spectator Mode Testing
|
|
- Join as spectator during active game
|
|
- Verify read-only constraints
|
|
- Test late join (mid-game)
|
|
- Multi-spectator scenarios
|
|
|
|
### Animation Testing
|
|
- Verify timing synchronization
|
|
- Test on various devices/browsers
|
|
- Performance impact measurement
|
|
- Reduced motion preference
|
|
|
|
### Accessibility Testing
|
|
- Screen reader testing (NVDA, JAWS, VoiceOver)
|
|
- Keyboard-only navigation
|
|
- Color contrast validation tools
|
|
- Automated accessibility audits (axe, Lighthouse)
|
|
|
|
### Performance Testing
|
|
- Lighthouse audits
|
|
- Mobile device testing (real devices)
|
|
- Network throttling tests (3G simulation)
|
|
- Memory leak detection
|
|
|
|
## Key Files to Create/Modify
|
|
|
|
**Backend**:
|
|
- `backend/app/websocket/handlers.py` - Add spectator events
|
|
- `backend/app/api/routes/spectate.py` - Spectator endpoints
|
|
|
|
**Frontend**:
|
|
- `shared-components/src/components/Display/DiceRoll.vue` - Animation
|
|
- `shared-components/src/components/Common/LoadingStates.vue`
|
|
- `frontend-{league}/pages/spectate/[id].vue` - Spectator view
|
|
- `frontend-{league}/composables/useAccessibility.ts`
|
|
- `frontend-{league}/utils/animations.ts`
|
|
|
|
**Styles**:
|
|
- `frontend-{league}/assets/css/animations.css`
|
|
- `frontend-{league}/assets/css/accessibility.css`
|
|
|
|
## Reference Documents
|
|
|
|
- [Frontend Architecture](./frontend-architecture.md) - Component structure
|
|
- [WebSocket Protocol](./websocket-protocol.md) - Spectator events
|
|
- [PRD Lines 233-245](../prd-web-scorecard-1.1.md) - Spectator requirements
|
|
- [PRD Lines 732-777](../prd-web-scorecard-1.1.md) - UX requirements
|
|
|
|
## Deliverable
|
|
|
|
A production-ready game interface with:
|
|
- Spectator mode allowing real-time viewing
|
|
- Polished animations and transitions
|
|
- Optimized mobile touch experience
|
|
- WCAG 2.1 AA accessibility compliance
|
|
- Robust error handling and recovery
|
|
- Performance meeting target metrics
|
|
|
|
## Performance Targets
|
|
|
|
- Page load: < 3s on 3G
|
|
- Action response: < 500ms
|
|
- Lighthouse score: > 90
|
|
- Accessibility score: 100
|
|
- First contentful paint: < 1.5s
|
|
- Time to interactive: < 3.5s
|
|
|
|
## Accessibility Checklist
|
|
|
|
- [ ] All interactive elements keyboard accessible
|
|
- [ ] Focus indicators visible and clear
|
|
- [ ] Color contrast meets WCAG AA standards
|
|
- [ ] Screen reader announcements for game events
|
|
- [ ] Alternative text for all images
|
|
- [ ] Form labels and error messages
|
|
- [ ] Skip navigation links
|
|
- [ ] Semantic HTML structure
|
|
- [ ] Reduced motion preference respected
|
|
- [ ] ARIA attributes used correctly
|
|
|
|
## Notes
|
|
|
|
- Test spectator mode with multiple simultaneous spectators
|
|
- Animation should enhance, not distract from gameplay
|
|
- Mobile touch targets must be large enough for thumbs
|
|
- Accessibility is not optional - it's a requirement
|
|
- Performance directly impacts user retention
|
|
|
|
---
|
|
|
|
**Status**: Placeholder - to be expanded during implementation
|
|
**Next Phase**: [05-testing-launch.md](./05-testing-launch.md) |