# CrewCompanion App - Project Summary for Migration

This document outlines the features, logic, and configuration of the CrewCompanion application to assist in recreating it on a different platform.

## 1. Core Features

- **Timezone-Aware Alarms:** Users can create, edit, and delete alarms. The dashboard intelligently separates alarms into "Home" and "Current Location" groups based on the user's GPS and pre-configured home timezone.
- **Dynamic Weather Card:** Displays a 4-day weather forecast based on the user's GPS. It also includes a search function to look up weather for any city or airport code.
- **Currency Converter:** Automatically detects the local currency via GPS and provides a real-time conversion tool to and from the user's pre-configured home currency.
- **AI Trip Planner:** Users can input a destination (airport code), trip duration, and start date to receive an AI-generated packing list and a set of important, location-specific travel tips.
- **AI Bill Splitter:** A utility to split a bill between a number of people. It includes an AI-powered tipping guide that suggests appropriate tip percentages based on the current location (or a searched location). It calculates the total per person in both local and home currency.
- **Calculator:** A standard, simple calculator for quick math.
- **Room Number Reminder:** A simple input field where users can save their hotel room number locally on their device.
- **Customizable Dashboard:** From the settings panel, users can toggle the visibility of each feature card to customize their dashboard.
- **User Feedback System:** A floating button allows users to submit feedback, which is saved to a Firestore database.

## 2. Technical Logic & Flows

### a. Data and State Management

- **Client-Side State:** The main dashboard state (GPS location, weather data, etc.) is managed with React's `useState` and `useEffect` hooks.
- **Server Actions:** All backend logic and communication with external APIs or the database are handled through Next.js Server Actions. Client components call these actions to fetch data or perform mutations.
- **Global Settings:** User preferences like Home Timezone, Home Currency, and Card Visibility are stored in the browser's `localStorage` and managed globally through a React Context.

### b. Feature Logic

#### Alarms
- **Flow:** User clicks "New Alarm" -> A form sheet opens -> User fills out details -> A server action is called -> The action updates an in-memory alarms array.
- **Display:** A component fetches alarms and compares each alarm's timezone with the user's home timezone and current timezone (derived from GPS) to group them.

#### Weather
- **Flow (GPS):** The weather card component uses the GPS location from the main page -> It calls a server action -> This action fetches data from the WeatherAPI.
- **Flow (Search):** User types in the search box -> An event handler calls the weather server action with the query.
- **API:** A function makes a `fetch` call to the WeatherAPI.com API.

#### Currency & Tipping (Bill Splitter / Exchange Rate)
- **Flow:** The exchange rate and bill splitter cards get the GPS location -> They call a function to determine the local currency and then fetch the conversion rate from the ExchangeRate-API.
- **Tipping (GPS):** The bill splitter card calls a server action, which uses the weather data to find the location name, then calls a function to get cached tipping info.
- **Tipping (Search):** The user searches for a location -> a different server action is called, which follows the same logic.
- **Tipping Data Source:** A function first checks a local, pre-seeded data file. If found, it returns the data. If not, it returns null. The Firestore lookup has been removed for stability.

#### AI Trip Planner
- **Flow:** User fills in the form -> a server action is called -> It first calls a function to get a weather forecast.
- **AI Call:** It then passes the weather data to a Genkit flow.
- **Prompt:** The prompt instructs the AI to generate a packing list and important travel info based on the provided weather forecast and user-selected categories.

### c. Database (Firestore)
- **Collections:**
    - `/tippingCache/{locationId}`: Caches tipping information. (This is populated from a local data file).
    - `/feedback/{feedbackId}`: Stores user-submitted feedback.
    - `/errorLogs/{errorLogId}`: Stores client-side application errors.
- **Configuration:** Firebase is initialized in a client provider. You will need to replace the placeholder configuration with your own project's keys.

## 3. API Keys & Configuration

You need to create a file for environment variables (e.g., `.env`) with the following keys.

```
# From WeatherAPI.com (for weather forecasts)
WEATHER_API_KEY="dffbf8a6df5148dfaab65159250712"

# From ExchangeRate-API.com (for currency conversion)
EXCHANGE_RATE_API_KEY="a8cbafd0db31cade80f2b933"

# Your Firebase project configuration
# Get this from the Firebase Console (Project Settings > General)
NEXT_PUBLIC_FIREBASE_API_KEY="YOUR_API_KEY"
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN="YOUR_AUTH_DOMAIN"
NEXT_PUBLIC_FIREBASE_PROJECT_ID="YOUR_PROJECT_ID"
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET="YOUR_STORAGE_BUCKET"
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID="YOUR_MESSAGING_SENDER_ID"
NEXT_PUBLIC_FIREBASE_APP_ID="YOUR_APP_ID"

# Your Gemini API Key for Genkit AI flows
# Get this from Google AI Studio
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
```

## 4. AI Flows (Genkit)

- **Packing List Flow**:
    - **Input:** Weather data object and a list of information categories.
    - **Output:** A packing list and a list of important travel information.
    - **Logic:** Takes the forecast and categories and uses a Handlebars template to construct a detailed prompt for the Gemini model.

- **Tipping Guide Flow**:
    - **Input:** A location string (e.g., "Paris, France").
    - **Output:** A summary sentence and an array of three tip percentages.
    - **Logic:** Provides examples in the prompt to guide the AI into returning structured JSON data.

This summary should provide a solid foundation for rebuilding the application's logic in your target environment.