kidsai/README.md

# KidsAI Explorer 🚀

A beautiful, interactive bilingual frontend designed to help children develop critical thinking skills through guided AI assistance. Built with **Next.js 15**, **TypeScript**, **Tailwind CSS**, and runs fully containerized using **Docker Compose v2** with **Docker Bake** integration for optimal build performance.

## Features

✨ **Kid-Friendly Interface**: Vibrant space/adventure themed design that appeals to children aged 8-12  
🌍 **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 with floating stars, planets, and friendly robots  
📱 **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  
🐳 **Full Docker Integration**: Runs entirely in containers with Docker Bake support  

## Technology Stack

- **Frontend**: Next.js 15 with App Router
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **Containerization**: Docker + Docker Compose v2 + Docker Bake
- **Development**: Hot reload with volume mounting
- **Production**: Optimized multi-stage builds

## Quick Start with Docker

### Prerequisites

- Docker Desktop with Docker Compose v2
- Docker Buildx (for Bake support)

### Setup

1. **Clone and navigate to the project**:
   ```bash
   git clone <repository-url>
   cd kidsai
   ```

2. **Configure environment**:
   ```bash
   cp .env.example .env
   # Edit .env and add your API keys
   ```

3. **Start development environment**:
   ```bash
   ./docker-dev.sh dev
   ```

That's it! The application will be available at `http://localhost:3444`

## Docker Bake + Compose v2 Integration

This project uses **Docker Bake** with **Docker Compose v2** for optimized builds and better development experience:

### Features:
- ⚡ **Fast Builds**: Docker Bake provides parallel builds and better caching
- 🔄 **Multi-platform**: Builds for both `linux/amd64` and `linux/arm64`
- 📦 **Smart Caching**: GitHub Actions cache integration ready
- 🎯 **Multiple Targets**: Development and production optimized builds

### Available Commands:

```bash
./docker-dev.sh dev         # Start development with hot reload
./docker-dev.sh prod        # Start production environment  
./docker-dev.sh build       # Build with Bake (falls back to Compose)
./docker-dev.sh bake-all    # Build all targets with Bake
./docker-dev.sh logs        # View application logs
./docker-dev.sh shell       # Access container shell
./docker-dev.sh stop        # Stop all services
./docker-dev.sh clean       # Clean up containers and images
```

### Manual Docker Bake Usage:

```bash
# Build all targets
docker buildx bake

# Build specific target
docker buildx bake development
docker buildx bake production

# Build with custom registry
REGISTRY=myregistry/kidsai docker buildx bake
```

4. Open your browser and visit `http://localhost:3000`

## Usage

### For Children
- Choose your preferred language (English or German) using the flags at the top
- Type any question you're curious about
- Follow the thinking steps provided
- Choose research, experiment, or discussion activities
- Explore and discover answers through your own investigation

### For Educators and Parents
- Language switching makes it accessible to German and English speaking children
- Use as a tool to encourage critical thinking in both languages
- Monitor children's questions to understand their interests
- Use the suggested activities as starting points for learning projects
- Encourage children to share what they discover

## Language Support

The application supports both **English** and **German** with:

- Complete UI translation for all interface elements
- Language-specific thinking frameworks and guidance
- Culturally appropriate suggestions and examples
- Multilingual keyword detection for question categorization
- Persistent language selection (remembers your choice)

### Language Detection

The system intelligently detects question types in both languages:
- **Science**: "Why/Warum", "How/Wie", "What happens/Was passiert"
- **Math**: "Calculate/Rechnen", "Numbers/Zahlen", "Solve/Lösen"  
- **Technology**: "Computer", "Robot/Roboter", "Machine/Maschine"

## Question Categories

The system recognizes different types of questions and provides appropriate thinking frameworks:

- **Science Questions**: Focus on observation, hypothesis, and experimentation
- **Math Problems**: Emphasize problem breakdown and solution strategies  
- **Technology Questions**: Guide understanding of systems and processes
- **General Curiosity**: Provide flexible thinking frameworks for any topic

## Safety Features

- Encourages adult supervision for online research
- Promotes safe experimentation with household items
- Emphasizes discussion with trusted adults
- No direct answers that might bypass learning processes

## Future Enhancements

- Integration with educational AI APIs
- Progress tracking for individual children
- Curriculum alignment features
- Teacher dashboard for classroom use
- Voice interaction capabilities
- More sophisticated question analysis

## Contributing

This project is designed to grow with feedback from educators, parents, and children. Contributions are welcome!

## License

MIT License - Feel free to use and modify for educational purposes.

---

**Remember**: The best learning happens when children think for themselves! 🌟