# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Common Development Commands

- **Install dependencies**: `bun install`
- **Build frontend**: `bun run build:frontend`
- **Build admin panel**: `bun run build:admin`
- **Start server**: `bun run start` or `bun run server.ts`
- **Start admin panel**: `bun run admin` or `bun run admin-server.ts`
- **Frontend development**: `bun run dev:frontend`
- **Admin panel development**: `bun run dev:admin`
- **Manual batch process**: `bun run scripts/fetch_and_generate.ts`
- **Type checking**: `bunx tsc --noEmit`

## Architecture Overview

This is a RSS-to-podcast automation system built with Bun runtime, Hono web framework, React frontend, and SQLite database.

### Core Components

- **server.ts**: Main Hono web server serving UI and static content (port 3000)
- **admin-server.ts**: Admin panel server for management functions (port 3001 by default)
- **scripts/fetch_and_generate.ts**: Batch processing script that fetches RSS feeds, generates summaries, and creates audio files
- **services/**: Core business logic modules:
  - `config.ts`: Centralized configuration management with validation
  - `database.ts`: SQLite operations for episodes and feed tracking (includes feed deletion)
  - `llm.ts`: OpenAI integration for content generation and feed classification
  - `tts.ts`: Text-to-speech via VOICEVOX API
  - `podcast.ts`: RSS feed generation
- **frontend/**: Vite React SPA for browsing feeds and episodes

### Data Flow

1. RSS feeds listed in `feed_urls.txt` are processed daily
2. Latest articles are classified by category and summarized via OpenAI
3. Summaries are converted to audio using VOICEVOX
4. Episodes are stored in SQLite (`data/podcast.db`) with audio files in `public/podcast_audio/`
5. RSS feed is generated at `/podcast.xml` for podcast clients
6. Web UI serves the React frontend for browsing content

### Key Directories

- `data/`: SQLite database storage
- `public/podcast_audio/`: Generated MP3 files
- `frontend/dist/`: Built React application (served statically)

### Environment Configuration

The application uses `services/config.ts` for centralized configuration management. Required `.env` variables include:
- `OPENAI_API_KEY`: OpenAI API key (required)
- `VOICEVOX_HOST`: VOICEVOX server URL (default: http://localhost:50021)
- `VOICEVOX_STYLE_ID`: Voice style ID (default: 0)
- `ADMIN_PORT`: Admin panel port (default: 3001)
- `ADMIN_USERNAME`: Admin panel username (optional, for basic auth)
- `ADMIN_PASSWORD`: Admin panel password (optional, for basic auth)
- `DISABLE_INITIAL_BATCH`: Disable initial batch process on startup (default: false)
- Podcast metadata and other optional settings

Configuration is validated on startup. See README.md for complete list.

### Deployment

The application runs as two separate servers:
- **Main server (port 3000)**: Serves the web UI, podcast.xml, and static files
- **Admin server (port 3001)**: Provides management interface with feed CRUD operations and environment variable management

Both servers execute batch processing on startup and at regular intervals.

### Recent Improvements

- **Admin Panel**: Separate admin server with feed management, deletion, and environment variable configuration
- **Feed Management**: Added feed deletion functionality and active/inactive toggling
- **API Separation**: Moved all management APIs to admin server, keeping main server focused on content delivery
- **ES Module Compatibility**: Fixed all ES module issues and removed deprecated `__dirname` usage
- **Centralized Configuration**: Added `services/config.ts` for type-safe configuration management
- **Enhanced Error Handling**: Improved error handling and validation throughout the codebase
- **Type Safety**: Fixed TypeScript errors and added proper null checks
- **Code Structure**: Simplified RSS generation logic and removed code duplication
- **Path Resolution**: Standardized path handling using the config module