kidsai/README-DOCKER.md

# KidsAI Explorer - Next.js Docker Setup 🚀

A beautiful, interactive bilingual frontend designed to help children develop critical thinking skills through guided AI assistance. Now migrated to **Next.js 15** with **TypeScript**, **Tailwind CSS**, and running entirely in **Docker**.

## 🌟 New Features

- **Next.js 15**: Latest React framework with App Router
- **TypeScript**: Full type safety and better development experience
- **Tailwind CSS**: Modern utility-first CSS framework
- **Docker**: Complete containerization with Docker Compose v2
- **Framer Motion**: Smooth animations and transitions
- **Modern Architecture**: Clean component-based structure

## 🛠️ Tech Stack

- **Frontend**: Next.js 15, React 18, TypeScript
- **Styling**: Tailwind CSS, Framer Motion
- **AI Integration**: OpenAI API, Hugging Face (fallback)
- **Containerization**: Docker, Docker Compose v2
- **Languages**: English & German support

## 🚀 Quick Start

### Prerequisites

- Docker and Docker Compose v2
- Your API keys (OpenAI recommended)

### Installation

1. **Clone and navigate to the project**:
   ```bash
   cd /path/to/kidsai
   ```

2. **Set up environment variables**:
   ```bash
   cp .env.example .env
   # Edit .env with your API keys
   ```

3. **Build and run with Docker**:
   ```bash
   docker compose up --build
   ```

4. **Access the application**:
   - Open your browser to `http://localhost:3000`
   - The app will be running entirely in Docker

### Environment Variables

Create a `.env` file with:

```bash
# Required: OpenAI API Key for best experience
OPENAI_API_KEY=your_openai_api_key_here

# Optional: Hugging Face token for fallback
HUGGING_FACE_TOKEN=your_hugging_face_token_here
```

## 🐳 Docker Commands

```bash
# Build and start the application
docker compose up --build

# Run in background (detached mode)
docker compose up -d

# View logs
docker compose logs -f

# Stop the application
docker compose down

# Rebuild after code changes
docker compose down && docker compose up --build
```

## 📱 Features

✨ **Kid-Friendly Interface**: Colorful, animated design that appeals to children  
🌍 **Bilingual Support**: Full English and German language support with easy switching  
🧠 **Critical Thinking Focus**: Guides children through thinking processes rather than giving direct answers  
🎯 **Interactive Learning**: Step-by-step guidance for problem-solving  
🎨 **Beautiful Animations**: Engaging visual effects and smooth transitions  
📱 **Responsive Design**: Works perfectly on all devices  
🔍 **Smart Question Categories**: Different thinking frameworks for science, math, technology, and general questions  
💾 **Language Persistence**: Remembers your language preference  

## 🏗️ Project Structure

```
src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page
├── components/            # React components
│   ├── Header.tsx
│   ├── WelcomeSection.tsx
│   ├── QuestionSection.tsx
│   ├── ThinkingSection.tsx
│   └── LanguageProvider.tsx
├── lib/                   # Utilities and services
│   ├── ai-service.ts      # AI integration
│   └── translations.ts    # Language translations
└── types/                 # TypeScript type definitions
    └── index.ts
```

## 🔧 Development

### Local Development (with Docker)

1. **Start development server**:
   ```bash
   docker compose up
   ```

2. **Make changes**: Edit files and see live updates

3. **View logs**:
   ```bash
   docker compose logs -f app
   ```

### Adding Prisma (Optional)

If you want to add a database:

1. **Uncomment database service** in `docker-compose.yml`
2. **Install Prisma**:
   ```bash
   docker compose exec app npm install prisma @prisma/client
   ```
3. **Initialize Prisma**:
   ```bash
   docker compose exec app npx prisma init
   ```

## 🌍 Language Support

The application supports:
- **English (en)**: Full interface translation
- **German (de)**: Complete German localization
- Language preference is saved in browser storage

## 🤖 AI Integration

- **Primary**: OpenAI API (GPT-3.5-turbo)
- **Fallback**: Local guidance questions when AI is unavailable
- **Educational Focus**: Encourages thinking rather than providing direct answers

## 🔒 Security

- All secrets managed through environment variables
- API routes protected and validated
- No API keys exposed to frontend
- Docker container isolation

## 📚 Educational Philosophy

KidsAI Explorer is built on the principle that **learning happens best when children think for themselves**. Instead of providing immediate answers, it:

- Encourages curiosity and wonder
- Breaks complex questions into manageable steps
- Suggests safe ways to explore and experiment
- Promotes discussion with adults and peers
- Builds confidence in problem-solving abilities

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with Docker
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details

## 🆘 Troubleshooting

### Container Issues
```bash
# Clean rebuild
docker compose down --volumes
docker compose up --build

# Check logs
docker compose logs app
```

### Port Conflicts
If port 3000 is in use, modify `docker-compose.yml`:
```yaml
ports:
  - "3001:3000"  # Use port 3001 instead
```

### Performance Issues
- Ensure Docker has enough memory allocated (4GB+ recommended)
- Check available disk space for Docker volumes