✨ Cappie ✨

“Pequeños cambios, grandes logros.”

Cappie is a banking app with a Financial Coach (Normal mode) that turns your transactions into simple, explainable actions — inspired by Capital One’s friendly, trustworthy vibe.

• ✨ Project Description
• 🛠️ Technologies Used
• 🚀 Quick Start
• 🔌 API — Key Endpoints
• 🗄️ Database (MySQL) & Seed
• 👥 Team
• 🤝 Acknowledgements

Managing money is time-consuming and mentally taxing. Most banking apps are reactive (balances + lists) and don’t guide the user with clear, actionable steps. Budgets can be rigid or vague, and they rarely show the impact of small daily choices on weekly goals.

A Financial Coach inside a banking app that turns transactions into simple, explainable actions.

How the MVP (Normal mode) works

• “Tinder for spending” onboarding: quick swipes (✅ / ❌) to learn habits.
• Emoji + map-based history: fast, emotional visualization by category/location.
• Weekly goals + Savings Envelope: small, achievable targets and a ledger to “compensate now”.
• Explainable recommendations (the “why”): generated with Gemini, while metrics/rules run on-device for privacy.
• Coach Metrics & Opportunities: real-time metrics (needs, regrets, progress), and saving opportunities from “regret” expenses.
• AI-assisted classification: emoji/category suggestions and goal creation from a free-text prompt.

Expected outcome (MVP)

• Less friction to understand spending.
• Small changes that accelerate goals (“Pequeños cambios, grandes logros.”).
• A friendly, non-punitive experience aligned with Capital One’s spirit.

Requirements: Python 3.10+, MySQL 8+

# 1) Install deps
pip install -r requirements.txt

# 2) Environment variables (create .env — do NOT commit)
#   GEMINI_API_KEY=your_key
#   MYSQL_HOST=localhost
#   MYSQL_PORT=3306
#   MYSQL_DB=CapitalOne
#   MYSQL_USER=cappie_user
#   MYSQL_PASSWORD=change_me

# 3) Load database (see section below if you need a new user)
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS CapitalOne;"
mysql -u root -p CapitalOne < backend/HackMTYCapitalOne2025.sql

# (Optional) App DB user
mysql -u root -p -e "CREATE USER IF NOT EXISTS 'cappie_user'@'%' IDENTIFIED BY 'change_me';
GRANT ALL ON CapitalOne.* TO 'cappie_user'@'%'; FLUSH PRIVILEGES;"

# 4) Run API
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Docs:
# Swagger UI → http://localhost:8000/docs
# Redoc      → http://localhost:8000/redoc

Interactive docs: /docs (Swagger) · /redoc
Note: In SQL for utility-null use utility = 'not assigned' (not IS).

Schema (main tables)

Load seed

mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS CapitalOne;"
mysql -u root -p CapitalOne < backend/HackMTYCapitalOne2025.sql

# Optional: dedicated app user
mysql -u root -p -e "CREATE USER IF NOT EXISTS 'cappie_user'@'%' IDENTIFIED BY 'change_me';
GRANT ALL ON CapitalOne.* TO 'cappie_user'@'%'; FLUSH PRIVILEGES;"

• Capital One — inspiration and sponsorship.
• HackMTY 2025 — venue to build Cappie.
• Mentors & community who provided feedback and testing.