QUICKSTART.md

# Quick Start Guide

## For Local Development

### 1. Install Dependencies

```bash
cd /home/kashikuldeep/Desktop/dialect-map

# Install Python dependencies
pip install -r requirements.txt
# OR if you have externally managed Python:
pipx install -r requirements.txt
```

### 2. Configure Secrets

Choose ONE of these methods:

#### Method A: Using actual config files (easier for local dev)

```bash
# Copy templates
cp config.json.example config.json
cp credentials.json.example credentials.json

# Edit with your actual Google Cloud credentials
nano config.json        # Update spreadsheet IDs
nano credentials.json   # Paste your service account JSON
```

#### Method B: Using environment variables (simulates HF Spaces)

```bash
# Copy .env template
cp .env.example .env

# Edit .env with your actual JSON content
nano .env

# Set your actual spreadsheet IDs and credentials
```

### 3. Run the Application

```bash
# Start the app
python3 app.py

# Open your browser to:
# http://localhost:7860/index.html
```

The app will:
- ✅ Load secrets from environment or files
- ✅ Start Google Sheets sync automation (every 5 minutes)
- ✅ Serve the interactive map on port 7860

---

## For Hugging Face Spaces Deployment

See **[SECRETS_SETUP.md](SECRETS_SETUP.md)** for complete deployment instructions.

**Quick summary:**
1. Create a new Space on Hugging Face
2. Add two secrets in Space settings:
   - `HF_CONFIG_JSON` - your entire config.json content
   - `HF_CREDENTIALS_JSON` - your entire credentials.json content
3. Push your code to the Space
4. Access your live app!

---

## Files You Need

| File | Purpose | How to Get |
|------|---------|------------|
| `config.json` | App configuration with spreadsheet IDs | Copy from `config.json.example` and edit |
| `credentials.json` | Google service account credentials | Download from Google Cloud Console |

**Important:** These files are in `.gitignore` - never commit them!

---

## Troubleshooting

**"ModuleNotFoundError: No module named 'google'"**
- Install dependencies: `pip install -r requirements.txt`

**"HF_CONFIG_JSON not found"**
- You need to either:
  - Create `config.json` file locally, OR
  - Set `HF_CONFIG_JSON` environment variable

**"Credentials file not found"**
- Follow [SECRETS_SETUP.md](SECRETS_SETUP.md) steps 1.1-1.4 to get credentials

---

## What Gets Created

When you run `app.py`:
- `config.json` - Created from `HF_CONFIG_JSON` env var (if set)
- `credentials.json` - Created from `HF_CREDENTIALS_JSON` env var (if set)
- `sheets_output/*.csv` - Downloaded from Google Sheets
- `data/processed/*.json` - Converted from CSV files

All of these are in `.gitignore` and safe to regenerate.