Team: Warissa Hossain, Gemma Truong, Sky Tran, Jesus E. Gutierrez

Team 41 · BeachHack 9.0 — GitHub repo

FastAPI + Vite/React monorepo. Architecture, roles, and hackathon planning live under docs/MASTER_PLAN.md and docs/plans/ (T1–T4).

cd backend
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # optional: edit later for real keys
uvicorn app.main:app --reload --port 8000

• Health: http://127.0.0.1:8000/health
• OpenAPI: http://127.0.0.1:8000/docs

cd frontend
npm install
cp .env.example .env.local  # default points API at http://127.0.0.1:8000
npm run dev

Open the printed local URL (usually http://127.0.0.1:5173).

Do not commit real keys. Copy examples and fill locally:

Backend (pytest) — logic and request/response shape without requiring a real MongoDB or external APIs:

cd backend
source .venv/bin/activate
pytest

• Tests live in backend/tests/.
• Prefer pure functions and Pydantic models for anything you want easy unit coverage.

Frontend (Vitest) — components and small modules in isolation:

cd frontend
npm run test

Backend integration uses FastAPI’s TestClient to hit the real app in-process (Twilio/Mongo/Gemini still optional depending on .env):

cd backend
pytest -m integration

Run everything including integration-marked tests:

pytest

The integration marker is defined in backend/pytest.ini.

1. Terminal A: from backend/, run uvicorn app.main:app --reload --port 8000.
2. Terminal B: from frontend/, run npm run dev.
3. Confirm the UI shows healthy and a plan response from the API (stub if GEMINI_API_KEY is unset; otherwise Gemini).

For WhatsApp / Fetch / Mongo: add keys to backend/.env, then repeat and point Twilio sandbox + Fetch callbacks at your deployed HTTPS URL.

Use this checklist when Mongo + Twilio are configured. If Mongo is unavailable and the app falls back to demo mode, the UI and WhatsApp replies still work, but saved-plan/session checks below will not persist server-side.

1. Create a guest user and web plan from the onboarding flow. Expected: a single new plan-<plan_id> project appears in the web UI.
2. In WhatsApp, send PLAN finish linked lists assignment. Expected: WhatsApp replies with Plan ready plus the first step. The web app shows one plan project for that new plan_id, not duplicates.
3. Reply BUILD. Expected: WhatsApp returns the same saved plan. No second plans row should be created for that thread, and the web UI should still show one project for that plan_id.
4. Reply STUCK. Expected: the nudge resolves against the currently linked plan from WhatsApp rather than falling back to an unrelated task.
5. Reply DONE. Expected: WhatsApp replies with completion guidance, the linked thread keeps its active_plan_id, and Mongo records a completed session for that plan_id even if no session had been started before.
6. After DONE, send a free-form message like keep going. Expected: old grocery/task conversation text does not leak back in; the WhatsApp draft memory was cleared on DONE.
7. Optional: send PLAN a different task. Expected: WhatsApp seeds a fresh draft and saves a new canonical plan for that new task. The web UI switches to the new plan-<plan_id> project without creating duplicates for the same plan.

Production deploy (team default): Railway for backend/ (HTTPS). Vercel for frontend/; set VITE_API_URL to the Railway API origin. Add your Vercel URL(s) to backend CORS_ORIGINS on Railway. Details: docs/MASTER_PLAN.md and docs/plans/T4_DEVOPS_FETCH.md.

• Browser → VITE_API_URL (see frontend/.env.example).
• FastAPI enables CORS for local dev; in production include your Vercel origin(s) in CORS_ORIGINS.
• POST /plan returns the shared JSON shape; see docs/MASTER_PLAN.md.

backend/          FastAPI app, Pydantic schemas, routers, pytest
frontend/         Vite + React + TypeScript
docs/             Master plan + per-role playbooks (T1–T4)