QUICKSTART.md

Quick Start Guide

For Local Development

1. Install Dependencies

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)

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

# 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

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