BudgetBrawl is a hackathon webapp that turns your Google Calendar events into spending predictions and social betting challenges. Log in with Google, answer three spending habit questions, sync your next 7 days of calendar events, and Snowflake Cortex predicts how much you'll spend per event. Then challenge a friend to a $5 virtual bet on whether you'll stay under budget.

• Backend: FastAPI, Snowflake (database + Cortex LLM), Google OAuth, PyJWT, APScheduler
• Frontend: React 18, Vite, React Router v6, TypeScript, Axios
• AI: Snowflake Cortex COMPLETE('mistral-large2', ...) for spending predictions
• Auth: Google OAuth only (no email/password)

• Python 3.10+
• Node.js 18+
• A Snowflake account (use us-west-2 or us-east-1 region for Cortex availability)
• Google Cloud project with OAuth 2.0 credentials and Calendar API enabled

Run snowflake_setup.sql in Snowflake as ACCOUNTADMIN. This creates the database, schema, warehouse, role, and all tables.

The Cortex LLM grant is included in the setup script:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE BUDGETBRAWL_ROLE;

1. Create a project (or use an existing one).
2. Enable the Google Calendar API.
3. Create OAuth 2.0 Client ID credentials (Web application type).
4. Add http://localhost:8000/auth/callback as an authorized redirect URI.
5. Note your Client ID and Client Secret for the backend .env.

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Create backend/.env with the variables listed in the Environment Variables section below, then start the server:

uvicorn main:app --reload --port 8000

cd frontend
npm install

Create frontend/.env:

VITE_API_BASE_URL=http://localhost:8000

Start the dev server:

npm run dev

The frontend runs at http://localhost:5173.

All backend variables go in backend/.env.

Generate ENCRYPTION_KEY:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

BudgetBrawl/
├── snowflake_setup.sql        # Snowflake DDL (run as ACCOUNTADMIN)
├── backend/
│   ├── main.py                # FastAPI entrypoint, mounts all routers
│   ├── config.py              # Pydantic BaseSettings from .env
│   ├── database.py            # Snowflake connection + run_query helper
│   ├── scheduler.py           # APScheduler auto-forfeit job
│   ├── auth/                  # Google OAuth + JWT
│   ├── users/                 # User search/upsert
│   ├── onboarding/            # 3-question spending quiz
│   ├── friends/               # Friend requests
│   ├── calendar/              # Google Calendar sync
│   ├── predictions/           # Snowflake Cortex spending predictions
│   ├── challenges/            # Challenge state machine + wallet logic
│   └── wallet/                # Balance + transaction history
└── frontend/
    └── src/
        ├── App.tsx            # Routes + navigation
        ├── api/               # Axios client + per-domain API calls
        ├── contexts/          # AuthContext, WalletContext
        └── pages/             # Login, Onboarding, Dashboard, Friends,
                               # Challenges, Wallet