GengoTavern Development Guide
You are working with GengoTavern, a SillyTavern-inspired web app for practicing foreign languages with custom AI chatbots. This skill provides architecture guidance, development patterns, and key implementation details.
Project Overview
GengoTavern is a React-based chat application for language learning with AI characters. It features visual novel mode with sentiment-based character sprites and a dual storage strategy for cross-platform compatibility.
Build Commands
Use these commands for development and deployment:
`bun install` - Install dependencies`bun run dev` - Start development server with Vite`bun run build` - Build for production (creates single HTML file in dist/, renamed to GengoTavern.html)`bun run lint` - Run ESLint`bun run preview` - Preview production buildArchitecture
State Management (Context-Based)
The app uses React contexts for state management:
**AppContext** - Application-wide state (storage strategy, panels, modals)**CharacterContext** - Character management and CRUD operations**UserSettingsContext** - User preferences and API keysStorage Strategy
**Dual Storage System:**
`StorageManager` class handles both File System Access API (desktop) and localStorage (fallback)Automatic migration between storage strategiesCharacters stored as PNG files with embedded JSON metadataBackgrounds and sprites stored in organized directory structure**Key file:** `src/utils/storageManager.ts`
Component Organization
```
src/
├── components/ # React components organized by feature
├── contexts/ # React contexts for state management
├── utils/ # Utility functions and API clients
├── types/ # TypeScript interfaces
└── pages/ # Main application pages
```
Critical Files
**Core Application:**
`src/pages/App.tsx` - Main application component with chat functionality`src/utils/storageManager.ts` - Dual storage strategy implementation`src/utils/geminiAPI.ts` - Google Gemini API client`src/utils/promptBuilder.ts` - Chat prompt construction`src/utils/emotionClassifier.ts` - Multilingual sentiment analysis for visual novel mode**Configuration:**
`vite.config.ts` - Vite configuration with single-file plugin`biome.json` - Biome formatter configuration (tabs, double quotes)`eslint.config.js` - ESLint configurationKey Features
AI Integration
**Google Gemini API** for chat responses (`src/utils/geminiAPI.ts`)**Hugging Face Transformers** for multilingual sentiment analysisVisual novel mode with sentiment-based sprites (very_negative, negative, neutral, positive, very_positive)Storage Systems
File System Access API for desktop file managementPNG metadata embedding for character import/exportAutomatic migration between storage strategiesLanguage Learning Focus
Character-based conversation practiceEmotion detection for immersive experienceExport/import functionality for character sharingDevelopment Patterns
Character Management
Characters stored with chats, sprites, and metadataEach character can have multiple chat sessionsPNG files contain embedded character dataAlways check storage strategy before file operationsMessage Handling
Messages support editing, regeneration, and continuationError messages are handled separately with delete functionalitySentiment analysis happens asynchronously using multilingual modelEmotion/Sentiment System
**Implementation details:**
Uses `tabularisai/multilingual-sentiment-analysis` modelFive sentiment levels: `very_negative`, `negative`, `neutral`, `positive`, `very_positive`Sprites are organized by sentiment level for visual novel modeDefault fallback sentiment is "positive"**Key file:** `src/utils/emotionClassifier.ts`
File Operations
**Best practices:**
Always check storage strategy before file operationsHandle both filesystem and localStorage fallbacksUse sanitized filenames for cross-platform compatibilityTech Stack
**Runtime:** Bun (package manager and runtime)**Framework:** React 19 with TypeScript**Build Tool:** Vite**Output:** Single-file HTML for easy distribution**Design:** Mobile-responsive with collapsible panelsCommon Tasks
Adding a New Feature
1. Identify which context(s) need to be updated
2. Create components in appropriate feature directory
3. Update storage schema if persisting data
4. Handle both filesystem and localStorage cases
5. Test on both desktop (File System Access) and mobile (localStorage)
Modifying AI Behavior
1. Update prompt construction in `src/utils/promptBuilder.ts`
2. Adjust Gemini API parameters in `src/utils/geminiAPI.ts`
3. Test with multiple character personalities
4. Verify sentiment analysis accuracy for visual novel mode
Storage Changes
1. Update `StorageManager` class in `src/utils/storageManager.ts`
2. Implement migration logic for existing data
3. Test both storage strategies
4. Handle edge cases (permissions, quota limits)
Important Notes
The app builds to a single HTML file for easy distributionFile System Access API is only available in Chromium-based browserslocalStorage fallback ensures cross-browser compatibilitySentiment analysis model loads on demand (first use only)Character sprites should follow the five sentiment level naming convention