BetterLover

BetterLover is a Bitrefill-focused hackathon prototype for a period-aware care agent. It uses a FastAPI backend and Vite SPA frontend. The backend mocks a Clue-style cycle data import, detects the current menstrual cycle phase, generates a structured JSON engagement plan, and serves the precompiled SPA with uvicorn.

The product goal is not to replace emotional presence. It is to help someone be more observant, respectful, and practical when their partner's needs are changing across the menstrual cycle.

Prototype Flow

1. Connect the mock Clue data source.
2. Adjust personal settings such as budget, mood, and care style.
3. Generate a JSON plan from the mock agent layer.
4. Review suggested transactions in list or calendar view.

Cycle Phases

The planner maps the latest mock period start into one of four phases:

• Menstrual: comfort, warmth, low-friction support.
• Follicular: light planning, shared momentum, renewed energy.
• Ovulatory: playful attention, date support, social energy.
• Luteal: mental-load reduction, cravings, reassurance, calm presence.

Synthetic Dataset

The mock Clue export lives at:

backend/data/synthetic_clue_export.json

It contains 3 synthetic cycles from March 21, 2026 through June 17, 2026. Each cycle includes a cycleId, periodStart, source, and a list of readings.

Each reading includes:

• date: reading date.
• stage: menstrual, follicular, ovulatory, or luteal.
• flow: heavy, medium, light, or none.
• mood: current emotional signal.
• energy: 1-10 synthetic energy score.
• pain: 0-10 synthetic pain score.
• sleepHours: previous-night sleep estimate.
• cravings: food or comfort signals.
• symptoms: physical and emotional symptoms.
• note: natural-language context for the planner.

The backend loads this JSON file in backend/app/data.py. /api/mock-clue returns the dataset, and /api/plan uses it to generate the current care plan.

Demo Run

The frontend is already pre-bundled into frontend/dist/. For the demo, uvicorn serves the FastAPI API and the compiled SPA from one process.

Install backend dependencies with Python 3.13 or 3.12:

python3.13 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements.txt

Serve the bundled app:

. .venv/bin/activate
npm run backend

Open:

http://localhost:8000

Frontend Development

Only use this path when changing frontend source. The committed demo bundle lives in frontend/dist/.

Install frontend dependencies:

npm --prefix frontend install

Run Vite during development:

npm run dev

Open:

http://localhost:5173

After frontend changes, rebuild the bundle that uvicorn serves:

npm run build

Project Structure

backend/app/main.py           FastAPI app, API routes, SPA serving
backend/app/planner.py        Phase detection and JSON plan generation
backend/app/data.py           Synthetic dataset loader
backend/data/                 Synthetic Clue-style export
backend/app/schemas.py        Request validation models
backend/static/dev.html       Backend fallback before SPA build exists
frontend/index.html           Vite entry HTML
frontend/src/main.jsx         React SPA
frontend/src/api.js           API client helpers
frontend/src/styles.css       Responsive product UI
frontend/dist/                Pre-bundled SPA served by uvicorn
frontend/vite.config.js       Vite config and API proxy