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:

   cd /path/to/kidsai
   

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your API keys
   

3. Build and run with Docker:

   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:

# 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

# 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:

   docker compose up
   

2. Make changes: Edit files and see live updates

3. View logs:

   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:

   docker compose exec app npm install prisma @prisma/client
   

3. Initialize Prisma:

   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

# 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:

ports:
  - "3001:3000"  # Use port 3001 instead

Performance Issues

• Ensure Docker has enough memory allocated (4GB+ recommended)
• Check available disk space for Docker volumes