GengoTavern Development Guide

A comprehensive development guide for working with GengoTavern, a SillyTavern-inspired web application for practicing foreign languages with custom AI chatbots.

Overview

GengoTavern is a React-based chat application that combines language learning with AI characters. The app features a sophisticated dual storage strategy (File System Access API + localStorage fallback), sentiment-based visual novel mode, and seamless character import/export via PNG metadata embedding.

Build and Development Commands

```bash

Install dependencies

bun install

Start development server with Vite

bun run dev

Build for production (creates single HTML file in dist/, renamed to GengoTavern.html)

bun run build

Run ESLint

bun run lint

Preview production build

bun run preview

```

Project Architecture

Technology Stack

State Management Pattern

The application uses a context-based architecture with three primary contexts:

1. **AppContext** - Application-wide state (storage strategy, panels, modals)

2. **CharacterContext** - Character management and CRUD operations

3. **UserSettingsContext** - User preferences and API keys

Dual Storage Strategy

The `StorageManager` class (`src/utils/storageManager.ts`) implements a sophisticated storage system:

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/App.tsx # Main application component

```

Critical Files Reference

Core Application

Configuration

Key Features Implementation

AI Integration

**Google Gemini API:**

**Sentiment Analysis:**

Storage Systems

**Character Management:**

**File Operations Pattern:**

```typescript

// Always check storage strategy before file operations

if (storageStrategy === 'filesystem') {

// Use File System Access API

} else {

// Use localStorage fallback

}

```

**Asset Organization:**

Visual Novel Mode

**Emotion-Based Sprite System:**

Development Patterns

Character Management Pattern

```typescript

// Characters include:

// - Basic metadata (name, description, etc.)

// - Chat sessions array

// - Sprite collections organized by emotion

// - Background images

```

Message Handling Pattern

```typescript

// Messages support:

// - Editing existing messages

// - Regenerating AI responses

// - Continuing conversations

// - Error messages (handled separately with delete functionality)

```

Error Handling Pattern

```typescript

// Error messages:

// - Stored separately from regular messages

// - Can be deleted individually

// - Don't interfere with chat history

```

Best Practices

1. **Storage Operations:**

- Always verify storage strategy before file operations

- Handle both filesystem and localStorage cases

- Use sanitized filenames for cross-platform support

2. **State Management:**

- Use appropriate context for state (App/Character/UserSettings)

- Minimize unnecessary re-renders

- Keep contexts focused on single responsibilities

3. **AI Integration:**

- Handle API errors gracefully

- Provide user feedback during long operations

- Implement proper loading states

4. **Sentiment Analysis:**

- Run asynchronously to avoid UI blocking

- Provide fallback sentiment when model unavailable

- Cache results when appropriate

5. **Mobile Responsiveness:**

- Design with collapsible panels

- Test on various screen sizes

- Ensure touch-friendly interactions

Distribution

The build process creates a single self-contained HTML file (`GengoTavern.html`) for easy distribution. This file includes all JavaScript, CSS, and embedded assets, making it portable across different environments.

Language Learning Focus

GengoTavern is specifically designed for language practice:

Notes and Constraints