update claude and copilot instructions for accuracy
- fix global stores documentation (add GlobalAssetsStore location, remove UserStore) - correct error handling docs (typed exceptions via BaseApiClient, not Future.error) - add missing lint rules (avoid_redundant_argument_values, unnecessary_parenthesis) - fix emote factory methods (add all 4: fromTwitch, fromBTTV, fromFFZ, from7TV) - update build_runner commands to modern dart run syntax - add MobX reactions examples and API architecture section - align commit convention with actual repo style (lowercase, no prefixes) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Tommy Chow
parent
60f2a57abf
commit
da2eeee518
2 changed files with 61 additions and 94 deletions
24
.github/copilot-instructions.md
vendored
24
.github/copilot-instructions.md
vendored
|
|
@ -15,19 +15,20 @@ Frosty is a cross-platform Flutter app for Twitch that supports third-party emot
|
|||
- `flutter build apk` - Build Android APK
|
||||
- `flutter build ios` - Build iOS app
|
||||
- `flutter analyze` - Run static analysis and lint checks
|
||||
- `flutter test` - Run all tests
|
||||
|
||||
### Code Generation (REQUIRED)
|
||||
|
||||
All MobX stores and JSON models require code generation. **Always run after any MobX or model changes:**
|
||||
|
||||
```bash
|
||||
flutter packages pub run build_runner build --delete-conflicting-outputs
|
||||
dart run build_runner build --delete-conflicting-outputs
|
||||
```
|
||||
|
||||
**Alternative commands:**
|
||||
|
||||
- `flutter packages pub run build_runner build` - Generate code once
|
||||
- `flutter packages pub run build_runner watch` - Watch and regenerate code on changes
|
||||
- `dart run build_runner build` - Generate code once
|
||||
- `dart run build_runner watch` - Watch and regenerate code on changes
|
||||
|
||||
Generated `.g.dart` files are excluded from linting but must be committed to source control.
|
||||
|
||||
|
|
@ -45,7 +46,9 @@ flutter run --dart-define=clientId=YOUR_TWITCH_CLIENT_ID --dart-define=secret=YO
|
|||
|
||||
- **Store Pattern**: Each feature has stores in `lib/screens/{feature}/stores/` (not at screen root)
|
||||
- **Naming**: All stores end with `Store` suffix and have corresponding `.g.dart` files
|
||||
- **Global Stores**: `AuthStore` and `SettingsStore` in `lib/screens/settings/stores/`
|
||||
- **Global Stores**:
|
||||
- `AuthStore`, `SettingsStore` in `lib/screens/settings/stores/`
|
||||
- `GlobalAssetsStore` (shared emote/badge cache) in `lib/stores/`
|
||||
- **Dependency Injection**: Stores are provided via Provider in `main.dart` with shared HTTP client
|
||||
|
||||
### API Service Architecture
|
||||
|
|
@ -97,7 +100,7 @@ lib/screens/{feature}/
|
|||
### Model Generation
|
||||
|
||||
- **JSON Serialization**: Models use `@JsonSerializable()` with `.g.dart` companions
|
||||
- **Emote Architecture**: Base `Emote` class with platform-specific factories (`Emote.fromTwitch()`, `Emote.fromBTTV()`)
|
||||
- **Emote Architecture**: Base `Emote` class with platform-specific factories (`Emote.fromTwitch()`, `Emote.fromBTTV()`, `Emote.fromFFZ()`, `Emote.from7TV()`)
|
||||
|
||||
## Key Integration Points
|
||||
|
||||
|
|
@ -140,7 +143,7 @@ Analysis rules in `analysis_options.yaml`:
|
|||
- Package imports: `always_use_package_imports`
|
||||
- Trailing commas: `require_trailing_commas`
|
||||
- Final locals: `prefer_final_locals`
|
||||
- Additional rules: `directives_ordering`, `avoid_void_async`, `always_declare_return_types`
|
||||
- Additional rules: `directives_ordering`, `avoid_void_async`, `always_declare_return_types`, `avoid_redundant_argument_values`, `unnecessary_parenthesis`
|
||||
|
||||
**Important**: `.g.dart` files are excluded from analysis but must be committed to source control.
|
||||
|
||||
|
|
@ -166,7 +169,8 @@ autorun((_) => prefs.setString('settings', jsonEncode(settingsStore)));
|
|||
|
||||
### Error Handling
|
||||
|
||||
Use `Future.error()` for API failures, not exceptions.
|
||||
API services use typed exceptions via `BaseApiClient` (`lib/apis/base_api_client.dart`):
|
||||
- `ApiException`, `NetworkException`, `TimeoutException`, `ServerException`, `NotFoundException`, `UnauthorizedException`
|
||||
|
||||
## MobX Store Implementation
|
||||
|
||||
|
|
@ -174,7 +178,7 @@ Use `Future.error()` for API failures, not exceptions.
|
|||
|
||||
All stores follow `StoreBase with _$StoreName` pattern:
|
||||
|
||||
- Generate `.g.dart` files with `flutter packages pub run build_runner build`
|
||||
- Generate `.g.dart` files with `dart run build_runner build`
|
||||
- Use `@observable`, `@action`, and `@computed` annotations
|
||||
- Settings store uses `@JsonSerializable()` with automatic persistence via `autorun()`
|
||||
|
||||
|
|
@ -205,4 +209,8 @@ Settings automatically saved to SharedPreferences via MobX `autorun()` reaction.
|
|||
- **Custom Cache**: `CustomCacheManager` for media caching
|
||||
- **PiP Mode**: Custom implementation via git dependency
|
||||
|
||||
## Commit Convention
|
||||
|
||||
Commits use lowercase, descriptive messages without prefixes (e.g., `fix landscape bottom padding in chat bottom bar`, `add swipe pip gesture support`). Keep commits tightly scoped.
|
||||
|
||||
When working with this codebase, always consider MobX code generation requirements and the shared HTTP client pattern for API efficiency.
|
||||
|
|
|
|||
131
CLAUDE.md
131
CLAUDE.md
|
|
@ -4,74 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||
|
||||
## Development Workflow
|
||||
|
||||
**Plan Mode - In-Depth Planning**: When in plan mode, interview thoroughly before coding:
|
||||
|
||||
**Plan Mode**: When in plan mode, interview thoroughly before coding:
|
||||
- Ask detailed questions about technical implementation, UI/UX concerns, tradeoffs, and edge cases
|
||||
- Continue asking questions until all requirements and non-obvious decisions are clear
|
||||
- Don't begin implementation until all important details are resolved
|
||||
|
||||
**Pattern Consistency**: When implementing new code:
|
||||
|
||||
- Search the codebase to find existing usages and implementations
|
||||
- Prefer following established patterns, styles, and practices for consistency
|
||||
|
||||
## Skills & Plugins
|
||||
|
||||
Claude Code has access to specialized skills. Use them proactively based on context:
|
||||
|
||||
**`/feature-dev:feature-dev`** — Guided Feature Development
|
||||
- Use when: Planning or implementing new features, analyzing architecture, creating implementation blueprints
|
||||
- Trigger phrases: "add a feature", "implement", "build", "create new functionality"
|
||||
|
||||
**`/frontend-design:frontend-design`** — Production UI Components
|
||||
- Use when: Creating or improving UI components, widgets, screens, or visual design
|
||||
- Trigger phrases: "design", "build UI", "create a widget", "improve the interface"
|
||||
|
||||
**`/code-review:code-review`** — Code Quality Review
|
||||
- Use when: After writing or modifying code, before commits, reviewing changes
|
||||
- Trigger phrases: "review my code", "check this", "is this good?"
|
||||
- **Proactive**: Suggest after significant code modifications
|
||||
|
||||
**`/pr-review-toolkit:review-pr`** — Comprehensive PR Review
|
||||
- Use when: Before creating PRs, reviewing PR changes, final quality checks
|
||||
- Trigger phrases: "review the PR", "check before merging", "PR ready?"
|
||||
|
||||
### Automatic Triggers
|
||||
|
||||
Claude should proactively suggest skills in these situations:
|
||||
|
||||
| After This Action | Suggest This Skill |
|
||||
|-------------------|-------------------|
|
||||
| Writing/editing multiple files | `/code-review:code-review` |
|
||||
| Completing a feature implementation | `/code-review:code-review` |
|
||||
| User says "ready for PR" or "create PR" | `/pr-review-toolkit:review-pr` |
|
||||
| Discussing new feature requirements | `/feature-dev:feature-dev` |
|
||||
| Building UI components or screens | `/frontend-design:frontend-design` |
|
||||
|
||||
### Specialized Subagents
|
||||
|
||||
These are advanced capabilities Claude can use for deeper analysis (not slash commands, but can be requested):
|
||||
|
||||
**Code Quality & Review:**
|
||||
- **Silent Failure Hunter** — Finds silent failures, poor error handling, swallowed exceptions
|
||||
- Trigger: "hunt for silent failures", "check error handling", "find swallowed errors"
|
||||
- **Code Simplifier** — Simplifies code while preserving functionality
|
||||
- Trigger: "simplify this code", "make this cleaner", "reduce complexity"
|
||||
- **Comment Analyzer** — Checks comments for accuracy and technical debt
|
||||
- Trigger: "review the comments", "check documentation accuracy"
|
||||
|
||||
**Architecture & Types:**
|
||||
- **Type Design Analyzer** — Analyzes type design, encapsulation, and invariants
|
||||
- Trigger: "analyze type design", "review this type", "check encapsulation"
|
||||
- **Code Architect** — Designs feature architectures with implementation blueprints
|
||||
- Trigger: "design the architecture", "create implementation blueprint"
|
||||
- **Code Explorer** — Deep analysis of existing features, traces execution paths
|
||||
- Trigger: "trace this flow", "how does this work end-to-end", "analyze this feature"
|
||||
|
||||
**Testing:**
|
||||
- **PR Test Analyzer** — Reviews test coverage quality and identifies gaps
|
||||
- Trigger: "analyze test coverage", "are tests thorough enough", "find test gaps"
|
||||
|
||||
## Development Commands
|
||||
|
||||
**Common Commands:**
|
||||
|
|
@ -82,9 +23,9 @@ These are advanced capabilities Claude can use for deeper analysis (not slash co
|
|||
- `flutter build apk` / `flutter build ios` - Build release binaries
|
||||
|
||||
**Code Generation** (required after changing MobX stores or `@JsonSerializable` models):
|
||||
- `flutter packages pub run build_runner build` - Generate once
|
||||
- `flutter packages pub run build_runner build --delete-conflicting-outputs` - Force rebuild all
|
||||
- `flutter packages pub run build_runner watch` - Watch mode for development
|
||||
- `dart run build_runner build` - Generate once
|
||||
- `dart run build_runner build --delete-conflicting-outputs` - Force rebuild all
|
||||
- `dart run build_runner watch` - Watch mode for development
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
|
|
@ -106,11 +47,11 @@ These are advanced capabilities Claude can use for deeper analysis (not slash co
|
|||
3. Settings persisted via `SettingsStore` with SharedPreferences and MobX `autorun()`
|
||||
4. API services share a common Dio HTTP client for efficient connection reuse
|
||||
|
||||
**Global Stores** (provided at app root in `main.dart`):
|
||||
**Global Stores** (injected via Provider in `main.dart`):
|
||||
|
||||
- `AuthStore` - Authentication state and token management
|
||||
- `SettingsStore` - User preferences with automatic persistence via MobX `autorun()`
|
||||
- `GlobalAssetsStore` - Shared cache for global emotes and badges across all chat tabs
|
||||
- `AuthStore` (`lib/screens/settings/stores/`) - Authentication state and token management
|
||||
- `SettingsStore` (`lib/screens/settings/stores/`) - User preferences with automatic persistence via MobX `autorun()`
|
||||
- `GlobalAssetsStore` (`lib/stores/`) - Shared cache for global emotes and badges across all chat tabs
|
||||
|
||||
**HTTP & Auth**: Centralized Dio client (`DioClient.createClient()`) with connection pooling and optimized timeouts. `TwitchAuthInterceptor` auto-injects auth headers for Twitch API URLs. `UnauthorizedInterceptor` catches 401 errors for token refresh. Two-tier token system: default app token + optional user token in Flutter Secure Storage.
|
||||
|
||||
|
|
@ -133,37 +74,55 @@ abstract class SomeStoreBase with Store {
|
|||
}
|
||||
```
|
||||
|
||||
After any changes to MobX stores or `@JsonSerializable()` models, run the build_runner to regenerate `.g.dart` files.
|
||||
**MobX Reactions** (for side effects and persistence):
|
||||
|
||||
```dart
|
||||
// Auto-save settings whenever they change (in main.dart)
|
||||
autorun((_) => prefs.setString('settings', jsonEncode(settingsStore)));
|
||||
|
||||
// React to specific state changes
|
||||
reaction((_) => authStore.isLoggedIn, (_) => _selectedIndex = 0);
|
||||
```
|
||||
|
||||
## Chat System Architecture
|
||||
|
||||
- **Real-time IRC**: WebSocket connection to Twitch IRC with custom `IRCMessage` parsing
|
||||
- **Third-party Emotes**: Asynchronous loading of BTTV, FFZ, and 7TV assets via dedicated APIs
|
||||
- **Message Management**: 5000 message limit with 20% batch removal optimization
|
||||
- **Assets Store**: Separate `ChatAssetsStore` manages channel-specific emotes/badges; `GlobalAssetsStore` caches global assets
|
||||
- **Assets Store**: `ChatAssetsStore` manages channel-specific emotes/badges
|
||||
|
||||
## Deep Linking
|
||||
## Additional Patterns
|
||||
|
||||
App supports Twitch channel deep links (e.g., `twitch.tv/channelname`). Deep link handling in `main.dart`:
|
||||
- Uses `app_links` package for URI stream handling
|
||||
- Resolves channel names via Twitch API before navigation
|
||||
- Graceful fallback with in-app browser option on failure
|
||||
**Emote Architecture**: Base `Emote` class with platform-specific factories: `Emote.fromTwitch()`, `Emote.fromBTTV()`, `Emote.fromFFZ()`, `Emote.from7TV()`.
|
||||
|
||||
**Custom Cache Manager**: Uses 30-day stale period and 10k max objects. `CustomCacheManager.removeOrphanedCacheFiles()` runs on startup to clean files not in database.
|
||||
|
||||
**Secure Storage Cleanup**: First-run detection clears Flutter Secure Storage to handle Android/iOS uninstall edge case where secure storage persists but app data is wiped.
|
||||
|
||||
## API Architecture
|
||||
|
||||
**BaseApiClient Pattern**: All API services (`TwitchApi`, `BTTVApi`, `FFZApi`, `SevenTVApi`) extend `BaseApiClient` which provides:
|
||||
- Generic GET/POST/PUT/DELETE methods with centralized error handling
|
||||
- Automatic conversion of `DioException` to typed exceptions
|
||||
|
||||
**Exception Hierarchy** (in `lib/apis/base_api_client.dart`):
|
||||
- `ApiException` - Base class for all API errors
|
||||
- `NetworkException` - Connection errors (no internet)
|
||||
- `TimeoutException` - Request timeouts
|
||||
- `ServerException` - 5xx server errors
|
||||
- `NotFoundException` - 404 errors
|
||||
- `UnauthorizedException` - 401 errors (triggers token refresh)
|
||||
|
||||
## Code Style
|
||||
|
||||
Analysis rules enforced via `analysis_options.yaml`:
|
||||
**Lint Rules** (from `analysis_options.yaml`):
|
||||
- `prefer_single_quotes`, `always_use_package_imports`, `require_trailing_commas`
|
||||
- `prefer_final_locals`, `prefer_final_in_for_each`, `avoid_redundant_argument_values`
|
||||
- `directives_ordering`, `avoid_void_async`, `always_declare_return_types`, `unnecessary_parenthesis`
|
||||
|
||||
- `prefer_single_quotes` - Use single quotes for strings
|
||||
- `always_use_package_imports` - Package imports over relative imports
|
||||
- `require_trailing_commas` - Trailing commas on multi-line constructs
|
||||
- `prefer_final_locals`, `prefer_final_in_for_each` - Prefer final variables
|
||||
- `directives_ordering`, `avoid_void_async`, `always_declare_return_types`
|
||||
- `avoid_redundant_argument_values`, `unnecessary_parenthesis`
|
||||
|
||||
Generated `.g.dart` files are excluded from analysis but must be committed.
|
||||
|
||||
**Error Handling**: Use `Future.error()` for API failures rather than throwing exceptions.
|
||||
**Other**:
|
||||
- Generated `.g.dart` files must be committed alongside source changes
|
||||
|
||||
## Commit Convention
|
||||
|
||||
Commits follow conventional format: `refactor:`, `feat:`, `fix:`, `format:`, etc. Keep commits tightly scoped. Include generated `.g.dart` outputs in the same commit as their source changes.
|
||||
Commits use lowercase, descriptive messages without prefixes (e.g., `fix landscape bottom padding in chat bottom bar`, `add swipe pip gesture support`). Keep commits tightly scoped.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue