PROJECT OVERVIEW:
The goal is to create a single-page React application that allows users to run the Gemma 4 AI model entirely offline on their iOS devices (simulated for web). This app, tentatively named 'Gemma AI: Çevrimdışı Akıl Yürütme Asistanı', aims to bring advanced, high-performance AI capabilities directly to the user's smartphone without requiring an internet connection. The core value proposition is empowering users with powerful AI tools for reasoning, analysis, and task execution, ensuring data privacy and offline accessibility. This addresses the growing need for on-device AI that respects user privacy and functions reliably in various network conditions.
TECH STACK:
- Frontend Framework: React (using Vite for a fast development experience)
- Styling: Tailwind CSS for rapid UI development and consistent design.
- State Management: Zustand for simple and efficient global state management.
- WebAssembly: TensorFlow.js or ONNX Runtime Web for running the Gemma 4 model (or a compatible smaller variant) in the browser via WebAssembly.
- Local Storage: To store model files and user preferences.
- Icons: Heroicons or similar.
- Deployment: Vercel or Netlify for easy deployment of a static SPA.
CORE FEATURES:
1. **Model Download & Management:**
* User Flow: Upon first launch, the app prompts the user to download the Gemma 4 model (or a compressed/optimized version suitable for mobile). A progress indicator is shown. Once downloaded, the model is stored locally. Users can check the download status and potentially manage storage space.
* Details: The model download should be handled efficiently, possibly in chunks. The app needs to provide clear feedback on download progress and completion.
2. **Offline Inference Engine:**
* User Flow: After the model is downloaded, the user can input text prompts into a dedicated input field.
* Details: When the user submits a prompt, the app sends it to the locally running Gemma 4 model via the WebAssembly runtime. The model processes the prompt and generates a response.
3. **Thinking Mode Interface:**
* User Flow: A primary chat-like interface where users type prompts and receive AI-generated responses. Each prompt-response pair forms a conversation turn. Users can scroll through the conversation history.
* Details: The interface should clearly distinguish between user input and AI output. Input field should support multi-line text. Responses should be displayed clearly, possibly with syntax highlighting for code.
4. **Basic Agent Skills (MVP):**
* User Flow: Users can select from a predefined list of agent skills (e.g., 'Summarize Text', 'Generate Code Snippet'). They then provide the necessary input (e.g., the text to summarize, programming language and task for code generation). The AI performs the specific task.
* Details: These skills are essentially specialized prompts or configurations for the Gemma 4 model. The UI should provide simple forms or input areas tailored to each skill.
5. **Settings & Status:**
* User Flow: A dedicated section to view model status (downloaded/downloading/error), manage storage, and potentially adjust basic settings (e.g., clear chat history).
* Details: Clear indicators for model availability and storage usage are crucial.
UI/UX DESIGN:
- **Layout:** Single-page application (SPA) with a clean, intuitive layout. A main content area for the chat/interaction, a navigation (perhaps a sidebar or bottom tab) for accessing different modes (Chat, Agent Skills, Settings). Minimalistic aesthetic.
- **Color Palette:** Primarily dark mode for a modern, focused feel. Use a deep charcoal background, with accents of a vibrant but not overpowering color (e.g., a cool blue or teal) for interactive elements, buttons, and AI responses. White or light gray for user text and standard UI elements.
- **Typography:** Clean, readable sans-serif font (e.g., Inter, Roboto). Clear hierarchy using font weights and sizes for headings, body text, and UI labels.
- **Responsive Design:** The app must be fully responsive. On larger screens, a two-column layout might be feasible (e.g., chat on one side, settings/options on the other). On mobile, a single-column, vertically scrolling layout is essential. Use Tailwind's responsive modifiers (`sm:`, `md:`, `lg:`).
- **Key Components:** Input area with send button, conversation display area (scrollable), buttons for agent skills, modal/drawer for settings, progress indicators for downloads.
COMPONENT BREAKDOWN:
- **`App.jsx`:** Main application component. Manages routing (if any, though likely not for SPA), global layout, and theme context. Initializes state management.
- Props: None
- Responsibility: Root component, layout.
- **`ChatInterface.jsx`:** The core component for prompt input and displaying conversation history.
- Props: `messages` (array), `onSendMessage` (function), `isLoading` (boolean)
- Responsibility: Handles user input, displays messages, manages sending logic.
- **`Message.jsx`:** Renders a single message (either user or AI).
- Props: `sender` (string: 'user' | 'ai'), `text` (string), `isCode` (boolean, optional)
- Responsibility: Displaying individual chat bubbles.
- **`ModelManager.jsx`:** Handles model download status, storage info, and potentially download initiation.
- Props: `modelStatus` (string), `downloadProgress` (number), `storageUsage` (string)
- Responsibility: UI for model management.
- **`AgentSkillSelector.jsx`:** Component to list and select available agent skills.
- Props: `skills` (array), `onSelectSkill` (function)
- Responsibility: Allows user to choose a specific AI task.
- **`SettingsPanel.jsx`:** Contains options for managing the app (e.g., clear history, view model info).
- Props: `onClearHistory` (function), `modelInfo` (object)
- Responsibility: App configuration and information.
- **`LoadingIndicator.jsx`:** A visual cue for when the AI is processing a request.
- Props: None
- Responsibility: Provides visual feedback during processing.
DATA MODEL:
- **State Structure (Zustand Store):**
```javascript
{
messages: [
{ id: '1', sender: 'ai', text: 'Merhaba! Size nasıl yardımcı olabilirim?', timestamp: Date.now() },
{ id: '2', sender: 'user', text: 'Gemma 4 modelini test ediyorum.', timestamp: Date.now() }
],
modelStatus: 'downloaded', // 'downloading', 'not_downloaded', 'error'
downloadProgress: 0, // 0-100
isProcessing: false, // boolean, indicates if AI is generating a response
availableSkills: ['Summarize Text', 'Generate Code Snippet', 'Translate Text'],
selectedSkill: null // null or the name of the selected skill
}
```
- **Mock Data Format (for `messages` array):**
```json
{
"id": "unique_message_id",
"sender": "user" | "ai",
"text": "The actual message content.",
"timestamp": 1678886400000 // Unix timestamp in milliseconds
}
```
- **Model File Storage:** Model weights and configuration files will be stored in the browser's local storage or IndexedDB for persistence. The path or identifier for the loaded model needs to be managed in the state.
ANIMATIONS & INTERACTIONS:
- **Message Appearance:** Smooth fade-in animation for new messages appearing in the chat history.
- **Send Button:** Subtle hover effect (slight scale up or color change).
- **Loading State:** When `isProcessing` is true, display a subtle pulsing animation or a typing indicator in place of the input field or below the last AI message.
- **Screen Transitions:** If any navigation between views occurs (e.g., opening settings), use a simple slide or fade transition.
- **Model Download:** Animated progress bar or circle during model download.
EDGE CASES:
- **Model Not Downloaded:** Gracefully prompt the user to download the model. Disable input until downloaded.
- **Download Error:** Display a clear error message and provide an option to retry.
- **Processing Error:** If the model fails during inference, show an error message to the user (e.g., 'An error occurred during processing. Please try again.').
- **Empty Input:** Prevent sending empty prompts. Provide visual feedback if the user tries.
- **Long Responses:** Ensure responses are scrollable within their container. Handle potential overflow.
- **Accessibility (a11y):** Use semantic HTML elements. Ensure sufficient color contrast. Add ARIA attributes where necessary, especially for interactive elements and status updates. Keyboard navigation should be fully supported.
- **Storage Full:** Detect if device storage is low before initiating a large model download. Provide warnings.
SAMPLE DATA:
1. **Initial AI Welcome Message:**
```json
{
"id": "msg_1",
"sender": "ai",
"text": "Merhaba! Ben Gemma AI, iPhone'unuzda çevrimdışı çalışan akıllı asistanınız. Bana bir soru sorabilir veya bir görev verebilirsiniz. Modelimin indirilmesi biraz zaman alabilir.",
"timestamp": 1700000000000
}
```
2. **User Prompt (General Query):**
```json
{
"id": "msg_2",
"sender": "user",
"text": "Yapay zeka etiği hakkında kısa bir özet yazar mısın?",
"timestamp": 1700000100000
}
```
3. **AI Response (General Query):**
```json
{
"id": "msg_3",
"sender": "ai",
"text": "Yapay zeka etiği, yapay zeka sistemlerinin tasarımı, geliştirilmesi ve uygulanmasıyla ilgili ahlaki ilkeleri ve değerleri inceler. Önemli konular arasında önyargı, şeffaflık, hesap verebilirlik, gizlilik ve otonom sistemlerin kontrolü bulunur.",
"timestamp": 1700000150000
}
```
4. **User Prompt (Code Generation Skill):**
```json
{
"id": "msg_4",
"sender": "user",
"text": "Javascript ile basit bir 'Merhaba Dünya' konsol logu yaz.",
"timestamp": 1700000200000
}
```
5. **AI Response (Code Generation Skill):**
```json
{
"id": "msg_5",
"sender": "ai",
"text": "```javascript\nconsole.log('Merhaba Dünya!');\n```",
"timestamp": 1700000250000
}
```
6. **Model Status Update:**
```json
// This would be reflected in the state, not a message
{
"modelStatus": "downloading",
"downloadProgress": 45
}
```
7. **User Prompt (Summarization Skill):**
```json
{
"id": "msg_6",
"sender": "user",
"text": "Please summarize the following article: [Long article text here...]",
"timestamp": 1700000300000
}
```
8. **AI Response (Summarization Skill):**
```json
{
"id": "msg_7",
"sender": "ai",
"text": "The article discusses the impact of renewable energy adoption on global carbon emissions, highlighting recent trends and future projections...",
"timestamp": 1700000350000
}
```
9. **Error State Example:**
```json
// State reflected, not a message
{
"modelStatus": "error",
"errorMessage": "Model download failed due to network issues."
}
```
10. **Loading State Example:**
```json
// State reflected, not a message
{
"isProcessing": true
}
```
DEPLOYMENT NOTES:
- **Build Configuration:** Use Vite's build command (`npm run build`). Ensure the output is a static site suitable for hosting on Vercel/Netlify.
- **Environment Variables:** While this is an offline-first app, any API keys for potential future features (like model fetching from a CDN) or analytics should be handled via environment variables.
- **Performance Optimizations:**
* Code Splitting: Vite handles this well by default.
* WebAssembly Optimization: Ensure the chosen WebAssembly runtime and model format are optimized for size and speed. Consider model quantization or using a smaller variant if Gemma 4 is too large.
* Lazy Loading: Load components like `ModelManager` or `SettingsPanel` only when they are needed.
* Image/Asset Optimization: Not critical for this text-heavy app, but ensure any icons are optimized.
- **Model Handling:** The process of downloading, storing, and loading the WebAssembly model requires careful implementation. Research best practices for handling large assets in a web environment, potentially using `localStorage` for smaller models or IndexedDB for larger ones, along with service workers for efficient caching and offline access.