From 856f8aebd28f5668262e21eb9dfa9056b3b3b265 Mon Sep 17 00:00:00 2001
From: Tommy Chow <tommyxchow@gmail.com>
Date: Sat, 23 Aug 2025 00:04:18 -0700
Subject: [PATCH] add ai files

---
 .github/copilot-instructions.md | 118 ++++++++++++++++++++++++++++++++
 GEMINI.md                       |  35 ++++++++++
 2 files changed, 153 insertions(+)
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 GEMINI.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000..706067cc
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,118 @@
+# Copilot Instructions for Frosty
+
+## Project Overview
+
+Frosty is a cross-platform Flutter app for Twitch that supports third-party emotes (7TV, BTTV, FFZ). The architecture is built around **MobX state management** with strict code generation requirements and a **shared HTTP client pattern** for API efficiency.
+
+## Critical Development Workflow
+
+### 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
+```
+
+Generated `.g.dart` files are excluded from linting but must be committed.
+
+### Environment Setup
+
+Twitch API requires client credentials via `--dart-define`:
+
+```bash
+flutter run --dart-define=clientId=YOUR_CLIENT_ID --dart-define=secret=YOUR_SECRET
+```
+
+## Architecture Patterns
+
+### State Management (MobX)
+
+- **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/`
+- **Dependency Injection**: Stores are provided via Provider in `main.dart` with shared HTTP client
+
+### API Service Architecture
+
+- **Shared HTTP Client**: Single `Client()` instance injected into all API services in `main.dart`
+- **API Services**: `TwitchApi`, `BTTVApi`, `FFZApi`, `SevenTVApi` in `lib/apis/`
+- **Headers Pattern**: Twitch API methods accept `headers` parameter for auth tokens
+
+### Screen Organization
+
+```
+lib/screens/{feature}/
+├── {feature}.dart          # Main UI
+├── {feature}_store.dart    # Feature store (NOT at root)
+├── {feature}_store.g.dart  # Generated file
+└── subdirectories/         # Feature sub-components
+```
+
+### Model Generation
+
+- **JSON Serialization**: Models use `@JsonSerializable()` with `.g.dart` companions
+- **Emote Architecture**: Base `Emote` class with platform-specific factories (`Emote.fromTwitch()`, `Emote.fromBTTV()`)
+
+## Key Integration Points
+
+### Firebase Services
+
+Initialized in `main.dart` with error handling:
+
+- Crashlytics for uncaught errors
+- Performance monitoring
+- Analytics
+
+### Chat System
+
+- **IRC Connection**: WebSocket to Twitch IRC for real-time chat
+- **Emote Loading**: Asynchronous third-party emote fetching (BTTV/FFZ/7TV)
+- **Message Parsing**: Custom rendering with emote/badge support
+
+### Authentication Flow
+
+- **OAuth**: Twitch OAuth via WebView in `AuthStore`
+- **Token Storage**: FlutterSecureStorage for secure token persistence
+- **Auto-refresh**: Token validation and refresh logic in `AuthStore`
+
+## Code Style Enforcement
+
+Analysis rules in `analysis_options.yaml`:
+
+- Single quotes: `prefer_single_quotes`
+- Package imports: `always_use_package_imports`
+- Trailing commas: `require_trailing_commas`
+- Final locals: `prefer_final_locals`
+
+## Common Patterns
+
+### MobX Reactions
+
+```dart
+late final ReactionDisposer _disposeReaction;
+_disposeReaction = reaction(
+  (_) => authStore.isLoggedIn,
+  (_) => _selectedIndex = 0,
+);
+```
+
+### Settings Persistence
+
+Auto-saving pattern in `main.dart`:
+
+```dart
+autorun((_) => prefs.setString('settings', jsonEncode(settingsStore)));
+```
+
+### Error Handling
+
+Use `Future.error()` for API failures, not exceptions.
+
+## Platform Support
+
+- **iOS/Android**: Native platform features via plugins
+- **Custom Cache**: `CustomCacheManager` for media caching
+- **PiP Mode**: Custom implementation via git dependency
+
+When working with this codebase, always consider MobX code generation requirements and the shared HTTP client pattern for API efficiency.
diff --git a/GEMINI.md b/GEMINI.md
new file mode 100644
index 00000000..a7153db2
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1,35 @@
+# GEMINI.md
+
+## Project Overview
+
+This project is a Flutter-based mobile application called "Frosty", a third-party client for the streaming platform Twitch. It aims to provide a better user experience by integrating with popular third-party services like BetterTTV (BTTV), FrankerFaceZ (FFZ), and 7TV, which are not supported by the official Twitch app.
+
+The application is built using the Flutter framework and the Dart programming language. It uses Firebase for analytics and crash reporting, and MobX for state management. The app is available for both Android and iOS.
+
+## Building and Running
+
+To build and run the project, you will need to have Flutter installed.
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/tommyxchow/frosty.git
+    ```
+2.  **Set up Twitch API credentials:**
+    *   Go to the [Twitch dev console](https://dev.twitch.tv/login) and register a new application to retrieve a **Client ID** and **Client Secret**.
+    *   Use `--dart-define` to set the `clientId` and `secret` environment variables with your **Client ID** and **Client Secret**.
+3.  **Install dependencies:**
+    ```bash
+    flutter pub get
+    ```
+4.  **Run the app:**
+    ```bash
+    flutter run
+    ```
+
+## Development Conventions
+
+*   **State Management:** The project uses MobX for state management. Code generation is required for MobX stores.
+*   **Code Style:** The project uses the `flutter_lints` package to enforce good coding practices.
+*   **Dependencies:** Dependencies are managed using the `pubspec.yaml` file.
+*   **Firebase:** The project uses Firebase for analytics and crash reporting. A `firebase_options.dart` file is used to configure the Firebase integration.
+*   **API Integration:** The application interacts with the Twitch API and other third-party APIs (BTTV, FFZ, 7TV) to fetch data.