GengoTavern Development Guide

GengoTavern is a SillyTavern-inspired web application for practicing foreign languages through conversations with custom AI chatbots. Built with React 19, TypeScript, and Vite, it features a dual storage strategy, Google Gemini AI integration, and a visual novel mode with multilingual sentiment analysis.

Build and Development Commands

```bash

Install dependencies

bun install

Start development server with Vite

bun run dev

Build for production (creates GengoTavern.html in dist/)

bun run build

Run ESLint

bun run lint

Preview production build

bun run preview

```

Project Architecture

State Management (Context-Based)

The application uses React Context API for state management across three primary contexts:

1. **AppContext** - Application-wide state

- Storage strategy (filesystem vs localStorage)

- Panel visibility and modal states

- Global UI state

2. **CharacterContext** - Character management

- CRUD operations for characters

- Character-specific chat sessions

- PNG metadata handling

3. **UserSettingsContext** - User preferences

- API keys (Google Gemini)

- Language settings

- Visual novel mode preferences

Storage Strategy

GengoTavern implements a **dual storage system** managed by the `StorageManager` class:

**Key file:** `src/utils/storageManager.ts`

Component Organization

```

src/

├── components/ # React components (feature-organized)

├── contexts/ # React contexts for state management

├── utils/ # Utility functions and API clients

├── types/ # TypeScript interfaces

└── pages/

└── App.tsx # Main application component

```

Critical Files Reference

| File | Purpose |

|------|---------|

| `src/pages/App.tsx` | Main app 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 logic |

| `src/utils/emotionClassifier.ts` | Multilingual sentiment analysis |

| `vite.config.ts` | Vite configuration with single-file plugin |

| `biome.json` | Biome formatter (tabs, double quotes) |

| `eslint.config.js` | ESLint configuration |

Key Features

AI Integration

Emotion/Sentiment System

The app uses multilingual sentiment analysis to create an immersive visual novel experience:

**Implementation:** `src/utils/emotionClassifier.ts`

Storage Systems

Development Guidelines

Technology Stack

Code Formatting

The project uses **Biome** for formatting:

Common Development Patterns

#### Character Management

Characters are the core entity in GengoTavern:

```typescript

// Characters stored with:

// - Embedded chats

// - Sprites (organized by sentiment)

// - Metadata (name, description, language, etc.)

// Each character supports:

// - Multiple chat sessions

// - PNG export with embedded data

// - Sprite upload for visual novel mode

```

**Pattern**: Always sanitize filenames for cross-platform compatibility when saving character files.

#### Message Handling

Messages support rich interactions:

**Pattern**: Check message type before applying operations (user vs assistant vs error).

#### File Operations

Always respect the storage strategy:

```typescript

// CORRECT: Check storage strategy before file operations

const storageManager = new StorageManager();

const strategy = await storageManager.getStorageStrategy();

if (strategy === 'filesystem') {

// Use File System Access API

} else {

// Use localStorage fallback

}

```

**Pattern**: Never assume filesystem access—always check and provide localStorage fallback.

#### Sprite Management (Visual Novel Mode)

Sprites are organized by sentiment level:

```

characters/{characterId}/sprites/

├── very_negative.png

├── negative.png

├── neutral.png

├── positive.png

└── very_positive.png

```

**Pattern**: When adding sprites, validate the sentiment level and store in the correct path.

Best Practices

1. **Storage-agnostic code**: Always check storage strategy before file operations

2. **Sanitized filenames**: Use cross-platform safe filenames for all file operations

3. **Graceful fallbacks**: Provide localStorage fallback for File System API features

4. **Async sentiment analysis**: Don't block message rendering on sentiment classification

5. **Context separation**: Keep state management separated by concern (App/Character/UserSettings)

6. **Single-file build**: The Vite config creates a single HTML file—ensure all assets are inlined

Common Tasks

Adding a New Character Field

1. Update TypeScript interface in `src/types/`

2. Modify `CharacterContext` to handle the new field

3. Update `storageManager.ts` PNG metadata embedding

4. Add UI controls in character creation/edit components

Integrating a New AI Provider

1. Create new API client in `src/utils/` (follow `geminiAPI.ts` pattern)

2. Add API key storage to `UserSettingsContext`

3. Update `promptBuilder.ts` if prompt format differs

4. Add provider selection UI in settings

Adding a New Sentiment Level

1. Update sentiment type definitions in `src/types/`

2. Modify `emotionClassifier.ts` mapping logic

3. Update sprite upload UI to support new level

4. Adjust `StorageManager` sprite path logic

Debugging Storage Issues

1. Check browser console for File System Access API permissions

2. Verify localStorage quota (especially on mobile)

3. Test migration logic by toggling storage strategies

4. Validate PNG metadata embedding/extraction

Language Learning Focus

GengoTavern is optimized for language learners:

Testing Checklist

When making changes, verify:

Resources

Notes