docs: Create comprehensive README documentation

- Updated main README with detailed setup, Kokoro model configuration, and troubleshooting - Enhanced backend README with API documentation, Docker setup, and testing instructions - Improved frontend README with component details, deployment guide, and development tips - Added workflow testing steps and common error solutions - Documented all supported languages, voices, and configuration options Implements task 14 from text-to-audiobook spec Requirements: 13.1, 13.2, 13.3, 13.4, 13.5
2025-12-09 10:11:15 +00:00
parent 50b0ef792a
commit ff2c8f8404
4 changed files with 1550 additions and 91 deletions
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,60 +1,555 @@
 # Text to Audiobook Frontend

-React TypeScript frontend for the Text to Audiobook application.
+React TypeScript single-page application for converting text to multi-voice audiobooks.

-## Setup
+## Overview

-### Prerequisites
+The frontend provides an intuitive interface for:
+- Text input with role marker support
+- Automatic role detection
+- Voice assignment per role
+- Language and speed configuration
+- Audio playback and download
+
+## Prerequisites

 - Node.js 20.19+ or 22.12+
 - npm or yarn
+- Backend service running (see [Backend README](../backend/README.md))

-### Installation
+## Installation

-1. Install dependencies:
 ```bash
+# Install dependencies
 npm install
-```

-2. Create environment file:
-```bash
+# Create environment file
 cp .env.example .env
 ```

-3. Update `.env` with your backend URL (default: `http://localhost:8000`)
+## Configuration
+
+Edit `.env` to configure the backend URL:
+
+```bash
+VITE_API_BASE_URL=http://localhost:8000
+```
+
+**For production:**
+```bash
+VITE_API_BASE_URL=https://your-backend-domain.com
+```

 ## Development

-Start the development server:
+### Start Development Server
+
 ```bash
 npm run dev
 ```

-The application will be available at `http://localhost:5173`
+The application will be available at http://localhost:5173

-## Build
+### Development Features
+
+- Hot Module Replacement (HMR)
+- Fast refresh for React components
+- TypeScript type checking
+- ESLint integration
+
+### Development Commands
+
+```bash
+# Start dev server
+npm run dev
+
+# Type check
+npm run type-check
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Production Build
+
+### Build for Production

-Build for production:
 ```bash
 npm run build
 ```

-Preview production build:
+Built files will be in `dist/` directory.
+
+### Preview Production Build
+
 ```bash
 npm run preview
 ```

+Preview server runs on http://localhost:4173
+
+### Build Optimization
+
+The production build includes:
+- Code minification
+- Tree shaking
+- Asset optimization
+- CSS purging (Tailwind)
+- Source maps (optional)
+
 ## Project Structure

 ```
-src/
-├── api/          # API client modules
-├── components/   # React components
-├── App.tsx       # Main application component
-├── main.tsx      # Application entry point
-└── index.css     # Global styles (Tailwind)
+frontend/
+├── src/
+│   ├── api/
+│   │   └── tts.ts                    # API client & TypeScript interfaces
+│   ├── components/
+│   │   ├── TextInputSection.tsx      # Text input component
+│   │   ├── VoiceAssignmentSection.tsx # Voice assignment UI
+│   │   └── AudioPlayerSection.tsx    # Audio playback component
+│   ├── App.tsx                       # Main application & state management
+│   ├── App.css                       # Application styles
+│   ├── main.tsx                      # Application entry point
+│   └── index.css                     # Global styles (Tailwind)
+├── public/
+│   └── vite.svg                      # Public assets
+├── index.html                        # HTML template
+├── package.json                      # Dependencies & scripts
+├── tsconfig.json                     # TypeScript configuration
+├── vite.config.ts                    # Vite configuration
+├── tailwind.config.js                # Tailwind CSS configuration
+├── postcss.config.js                 # PostCSS configuration
+├── eslint.config.js                  # ESLint configuration
+├── .env.example                      # Environment template
+└── README.md                         # This file
 ```

-## Environment Variables
+## Components

- `VITE_API_BASE_URL` - Backend API base URL (default: http://localhost:8000)
+### App Component (`App.tsx`)
+
+Main application container managing workflow state.
+
+**State:**
+- Text input
+- Detected roles
+- Voice assignments
+- Language selection
+- Speed setting
+- Audio URL
+- Loading states
+- Error handling
+
+**Phases:**
+1. Input - Text entry
+2. Assignment - Voice selection
+3. Generated - Audio playback
+
+### TextInputSection Component
+
+Text input interface with validation.
+
+**Features:**
+- Large multiline textarea
+- Character count (optional)
+- Validation for empty text
+- "Next: Assign voices" button
+- Loading state support
+
+### VoiceAssignmentSection Component
+
+Voice assignment and configuration interface.
+
+**Features:**
+- Role list with voice dropdowns
+- Language selector (American English, British English, French, Japanese)
+- Speed slider (0.5x - 1.5x)
+- "Generate Audiobook" button
+- Validation (all roles must have voices)
+
+### AudioPlayerSection Component
+
+Audio playback and download interface.
+
+**Features:**
+- HTML5 audio player with controls
+- Download button
+- Blob URL management
+
+## API Client
+
+### TypeScript Interfaces
+
+```typescript
+interface Role {
+  id: string;
+  label: string;
+}
+
+interface RoleWithVoice extends Role {
+  voice: string;
+}
+
+interface RolesResponse {
+  roles: Role[];
+}
+
+interface GenerateRequest {
+  text: string;
+  lang: string;
+  roles: { id: string; voice: string }[];
+  speed?: number;
+}
+```
+
+### API Functions
+
+```typescript
+// Detect roles in text
+async function detectRoles(text: string): Promise<RolesResponse>
+
+// Generate audiobook
+async function generateAudiobook(payload: GenerateRequest): Promise<Blob>
+
+// Health check
+async function checkHealth(): Promise<{ status: string }>
+```
+
+## Styling
+
+### Tailwind CSS
+
+The application uses Tailwind CSS for styling:
+
+- Utility-first CSS framework
+- Responsive design
+- Dark mode support (optional)
+- Custom color palette
+
+### Responsive Design
+
+Breakpoints:
+- Mobile: < 640px
+- Tablet: 640px - 1024px
+- Desktop: > 1024px
+
+All components are mobile-friendly with:
+- Touch-friendly controls (min 44x44px)
+- Responsive layouts
+- Readable text sizes
+- Appropriate spacing
+
+## Usage Workflow
+
+### 1. Text Input Phase
+
+User enters text with role markers:
+
+```
+Narrator: Once upon a time...
+Alice: Hello there!
+Bob: Hi Alice!
+```
+
+Supported patterns:
+- `RoleName:` - Colon pattern
+- `[RoleName]` - Bracket pattern
+
+### 2. Voice Assignment Phase
+
+- System detects roles automatically
+- User assigns voice to each role
+- User selects language
+- User adjusts speed (optional)
+
+### 3. Audio Generation Phase
+
+- Click "Generate Audiobook"
+- Loading indicator shows progress
+- Warning for long texts
+
+### 4. Playback Phase
+
+- Audio player appears
+- Play/pause/seek controls
+- Download button available
+
+## Error Handling
+
+### Network Errors
+
+- Connection failures
+- Timeout errors
+- Server unavailable
+
+**Display:** User-friendly error messages
+
+### Validation Errors
+
+- Empty text
+- Missing voice assignments
+- Invalid configurations
+
+**Display:** Inline validation messages
+
+### API Errors
+
+- 400 Bad Request
+- 500 Internal Server Error
+- Custom error messages
+
+**Display:** Error banner with details
+
+## Testing
+
+### Run Tests
+
+```bash
+npm test
+```
+
+### Test Coverage
+
+```bash
+npm run test:coverage
+```
+
+### Test Files
+
+- Component tests
+- API client tests
+- Integration tests
+- E2E tests (optional)
+
+## Browser Support
+
+### Supported Browsers
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Opera 76+
+
+### Required Features
+
+- ES2020 support
+- Fetch API
+- HTML5 Audio
+- Blob API
+- Local Storage (optional)
+
+## Performance
+
+### Optimization Techniques
+
+1. **Code splitting**: Dynamic imports for large components
+2. **Lazy loading**: Load components on demand
+3. **Memoization**: React.memo for expensive components
+4. **Debouncing**: Input handlers
+5. **Asset optimization**: Image compression, lazy loading
+
+### Performance Monitoring
+
+```bash
+# Analyze bundle size
+npm run build -- --analyze
+
+# Lighthouse audit
+npm run lighthouse
+```
+
+## Deployment
+
+### Static Hosting
+
+The built application can be deployed to:
+- Vercel
+- Netlify
+- GitHub Pages
+- AWS S3 + CloudFront
+- Any static file server
+
+### Deployment Steps
+
+1. Build the application:
+   ```bash
+   npm run build
+   ```
+
+2. Configure environment variables for production
+
+3. Deploy `dist/` directory to hosting service
+
+### Environment Variables in Production
+
+Set `VITE_API_BASE_URL` to your production backend URL:
+
+**Vercel:**
+```bash
+vercel env add VITE_API_BASE_URL
+```
+
+**Netlify:**
+Add to `netlify.toml`:
+```toml
+[build.environment]
+  VITE_API_BASE_URL = "https://api.yourdomain.com"
+```
+
+### Example nginx Configuration
+
+```nginx
+server {
+    listen 80;
+    server_name yourdomain.com;
+    root /var/www/text-to-audiobook;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Cache static assets
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+}
+```
+
+## Troubleshooting
+
+### Cannot connect to backend
+
+**Error:** Network request failed
+
+**Solutions:**
+1. Verify backend is running: `curl http://localhost:8000/api/health`
+2. Check `VITE_API_BASE_URL` in `.env`
+3. Verify CORS settings in backend
+4. Check browser console for details
+
+### Audio won't play
+
+**Error:** Audio playback failed
+
+**Solutions:**
+1. Check browser console for errors
+2. Verify audio format support (WAV)
+3. Try different browser
+4. Check audio permissions
+
+### Build fails
+
+**Error:** Build errors
+
+**Solutions:**
+```bash
+# Clear cache
+rm -rf node_modules dist
+npm install
+
+# Check Node version
+node --version  # Should be 20.19+ or 22.12+
+
+# Update dependencies
+npm update
+```
+
+### TypeScript errors
+
+**Error:** Type checking fails
+
+**Solutions:**
+```bash
+# Run type check
+npm run type-check
+
+# Check tsconfig.json
+# Verify all dependencies have types
+```
+
+### Styling issues
+
+**Error:** Tailwind classes not working
+
+**Solutions:**
+```bash
+# Rebuild Tailwind
+npm run build
+
+# Check tailwind.config.js
+# Verify PostCSS configuration
+```
+
+## Development Tips
+
+### Hot Reload Issues
+
+If HMR stops working:
+```bash
+# Restart dev server
+npm run dev
+
+# Clear Vite cache
+rm -rf node_modules/.vite
+```
+
+### Debugging
+
+```typescript
+// Enable debug mode
+localStorage.setItem('debug', 'true');
+
+// View API requests
+// Open browser DevTools → Network tab
+```
+
+### Code Quality
+
+```bash
+# Format code
+npm run format
+
+# Lint and fix
+npm run lint -- --fix
+
+# Type check
+npm run type-check
+```
+
+## Contributing
+
+### Code Style
+
+- Use TypeScript for type safety
+- Follow React best practices
+- Use functional components with hooks
+- Write meaningful component names
+- Add comments for complex logic
+
+### Component Guidelines
+
+1. Keep components small and focused
+2. Use props for configuration
+3. Lift state up when needed
+4. Use custom hooks for reusable logic
+5. Handle errors gracefully
+
+## Additional Resources
+
+- [React Documentation](https://react.dev/)
+- [TypeScript Documentation](https://www.typescriptlang.org/)
+- [Vite Documentation](https://vitejs.dev/)
+- [Tailwind CSS Documentation](https://tailwindcss.com/)
+- [Main Project README](../README.md)
+- [Backend Documentation](../backend/README.md)
+- [Design Document](../.kiro/specs/text-to-audiobook/design.md)
+
+## License
+
+MIT