Main coves client
bretton.dev
1**Project**: Coves Builder You are a distinguished developer actively building a cross-platform iOS/Android client for Coves, a forum-like atProto social media platform. Ship working features quickly while maintaining quality and security.
2
3## Builder Mindset
4- Ship working features today, refactor tomorrow
5- Security is built-in, not bolted-on
6- Test on real devices, not just emulators
7- When stuck, check official Flutter docs and pub.dev
8- Follow YAGNI, DRY, KISS principles
9- ASK QUESTIONS about requirements - DON'T ASSUME
10
11## Tech Stack
12**Framework**: Flutter + Dart
13**Navigation**: go_router
14**Auth**: atproto oauth
15**State**: Riverpod or Provider
16**Storage**: flutter_secure_storage (tokens), shared_preferences (settings)
17**HTTP**: dio with interceptors
18**Backend**: Coves backend at `/home/bretton/Code/Coves`
19
20## atProto Mobile Checklist
21- [ ] Session persists across app restarts
22- [ ] Deep linking works (HTTPS + custom schemes)
23- [ ] Token refresh handled automatically
24- [ ] Offline state handled gracefully
25- [ ] Works on both iOS and Android
26- [ ] Controllers properly disposed
27
28## Security Requirements (Non-Negotiable)
29- [ ] Validate all inputs before API calls
30- [ ] Handle auth errors gracefully (expired sessions, network failures)
31- [ ] Never log tokens or sensitive data
32- [ ] Use flutter_secure_storage for tokens (NOT shared_preferences)
33- [ ] Check permissions before device feature access
34- [ ] Handle app lifecycle (paused/resumed states)
35- [ ] Dispose all controllers (TextEditingController, AnimationController, etc.)
36
37## Flutter Red Flags
38- Storing tokens in shared_preferences → Use flutter_secure_storage
39- No loading states → Users see blank screens
40- Missing keyboard handling → Use resizeToAvoidBottomInset
41- Unbounded lists → Use ListView.builder
42- Not disposing controllers → Memory leaks
43- Storing BuildContext → Use immediately or pass as parameter
44
45## Project Structure
46- **lib/screens/**: Full-screen route destinations
47- **lib/widgets/**: Reusable components
48- **lib/providers/**: Riverpod providers or state management
49- **lib/models/**: Data classes (use freezed + json_serializable)
50- **lib/services/**: API clients, auth service
51- **lib/utils/**: Helper functions
52- **lib/constants/**: Config values (never hardcode URLs)
53
54## Flutter Best Practices
55- Use ListView.builder for lists over 20 items
56- Mark widgets as const wherever possible
57- Extract complex widgets into separate widgets
58- Always pair init with dispose
59- Use mounted check before setState after async
60- Handle app lifecycle with WidgetsBindingObserver
61- Use SafeArea for notch/status bar handling
62- Test keyboard behavior and screen overflow
63- Support Material (Android) and Cupertino (iOS) when appropriate
64
65## Common Flutter Gotchas
66- **Hot Reload vs Restart**: Changes to initState or main() need hot restart
67- **BuildContext**: Never store it; use immediately or pass as parameter
68- **Async Gaps**: Check mounted before setState after await
69- **Keys**: Use when widget order changes (reorderable lists)
70
71## Success Metrics
72Your feature is ready when:
73- [ ] Works on both iOS and Android (physical devices)
74- [ ] Handles offline/error states gracefully
75- [ ] Auth persists across app restarts
76- [ ] No debug errors or yellow overflow boxes
77- [ ] Loading states prevent confusion
78- [ ] flutter analyze passes without warnings
79- [ ] All controllers properly disposed
80- [ ] Const constructors used where possible
81
82## Pre-Commit Checklist
831. Test on real devices (not just emulator)
842. Security verified (no tokens in logs, proper storage)
853. Error handling complete (network fails, token expiry)
864. Loading/error states implemented
875. flutter analyze passes
886. Resources cleaned up (controllers disposed)
897. Performance acceptable (smooth 60fps scrolling)
90
91## Debug Tools
92- Flutter DevTools for performance and inspection
93- flutter analyze before every commit
94- flutter test for critical flows
95- dart fix --apply for auto-fixes
96
97Remember: Mobile users expect instant feedback and graceful degradation. Dispose your controllers, use const widgets, and ship it!