🌍 CultureCompass — Global Etiquette & Cultural Guide

An AI-powered chatbot that helps users explore customs, traditions, and etiquette from cultures around the world. Ask about dining manners in Japan, greeting rituals in the Middle East, or business customs in Europe — CultureCompass has you covered.

---

✨ Features

Feature	Description
🤖 AI-Powered Chat	Real-time cultural guidance powered by Groq's LLaMA 3.1 model for lightning-fast responses
🗺️ Region Explorer	One-click buttons to explore cultures from East Asia, South Asia, Europe, Middle East, Africa, and the Americas
💬 Quick Topics	Instant access to popular categories — Dining Etiquette, Greetings & Gestures, Business Customs, Festivals & Celebrations
📱 Responsive Design	Clean, modern UI that adapts to different screen sizes
⚡ Typing Indicator	Animated dots show when the AI is composing a response

---

🛠️ Tech Stack

• Frontend: HTML5, CSS3 (CSS Custom Properties), Vanilla JavaScript
• AI Backend: Groq API — OpenAI-compatible endpoint with llama-3.1-8b-instant
• Typography: Inter via Google Fonts
• Icons: Font Awesome 6.4

---

🚀 Getting Started

Prerequisites

• A modern web browser (Chrome, Firefox, Edge, Safari)
• A free Groq API Key
• Python 3.x (for local server) or any static file server

Installation

1. Clone the repository

   git clone https://github.com/Komalpreet2809/CultureCompass.git
   cd CultureCompass

2. Add your API key

   Open index.html and replace the placeholder API key on line 598 with your own Groq key:

   const GROQ_API_KEY = 'your_groq_api_key_here';

3. Run a local server

   python -m http.server 8000

4. Open in browser

   Navigate to http://localhost:8000

---

📂 Project Structure

CultureCompass/
├── index.html                                        # Main application (HTML + CSS + JS)
├── projectsnap.png                                   # Project screenshot
├── reshot-icon-round-travel-flights-MD53NY9TP2.svg   # Favicon & header logo
└── README.md                                         # Project documentation

---

💡 How It Works

1. User sends a message via the chat input or clicks a region/topic button.
2. The app constructs a prompt with a cultural etiquette system prompt and sends it to Groq's API.
3. The LLaMA 3.1 8B model generates a detailed, context-aware response.
4. The response is formatted (headings, bullet points, emphasis) and displayed in the chat window with a smooth fade-in animation.

---

🎨 UI Highlights

• CSS Custom Properties for seamless light/dark theme switching
• Gradient backgrounds and box shadows for a polished, modern look
• Micro-animations — hover effects on buttons, typing indicator dots, and fade-in transitions on messages
• Fixed footer with author branding

---

⚠️ Important Notes

API Key Security: The current implementation embeds the API key client-side for simplicity. For production use, consider proxying API calls through a backend server to keep your key secure.

Rate Limits: Groq's free tier has generous but finite rate limits. If you see errors, wait a few seconds and try again.

---

👩‍💻 Author

Komalpreet Kaur

• GitHub: @Komalpreet2809