Amity Expense Splitter

Amity is a sophisticated roommate expense splitting platform capable of handling complex financial relationships, household management, and automated governance. It features a modern React frontend and a robust FastAPI backend powered by MongoDB, integrated with advanced AI capabilities.

🚀 Key Features

💸 Financial Autopilot

• Smart Receipt Scanning: Snap a photo of any receipt. SwampHax uses Google Gemini Flash to extract merchant data, date, and line items, automatically splitting costs among roommates.
• Seamless Splitting: Expenses are instantly divided based on household rules.
• Banking Integration: Connect authentic bank accounts via the Capital One Nessie API to track balances and simulate real-time settlements.

🗳️ Democratic Governance

• Live Proposal Feed: Roommates can submit proposals (e.g., "Buy a new couch", "Quiet hours after 10 PM").
• Voting System: An interactive, tinder-style voting feed allowing household members to Approve or Reject motions.
• Legally Binding(ish): Tracks votes in real-time to enforce household decisions.

🤖 AI Utilities

• Amity Bot: Integrated generative AI (Gemini) helper for financial advice and dispute resolution.
• Voice Interface: ElevenLabs-powered voice interactions for hands-free operation.
• Receipt Scanner: Automated expense entry via receipt image scanning.

🤖 Amity AI Assistant

• Financial Advisor: Integrated chat widget powered by Google Gemini to answer questions about household finances ("Who spent the most on groceries this month?").

---

🛠️ Technology Stack

Frontend

• Framework: React 19 (Vite)
• Styling: Tailwind CSS v4, Glassmorphism design system
• Motion: Framer Motion for complex orchestrations
• State: Custom Hooks & Context API

Backend

• Core: Python 3.12, FastAPI
• Database: MongoDB (Motor Async Driver)
• AI Models: Google Gemini 1.5 Flash (Receipts & Chat)
• Voice: ElevenLabs (TTS) & Vonage (Telephony)
• Banking: Capital One Nessie API

Infrastructure

• Hosting: DigitalOcean Droplet (Ubuntu 22.04)
• Process Control: Systemd
• Server: Uvicorn (ASGI)

---

Backend

Prerequisites

• Python 3.12+
• Node.js 18+
• MongoDB Instance
• Python 3.12+
• Node.js 18+
• MongoDB Instance

1. Backend Setup

cd swamphax
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Create .env file with API keys (Gemini, Vonage, Nessie, MongoDB)
# Create .env file with API keys (Gemini, Vonage, Nessie, MongoDB)
uvicorn api.main:app --reload --port 8000

2. Frontend Setup

cd frontend
npm install
npm run dev

---

🔒 Configuration

The application requires the following environment variables in api/.env:

Variable	Description
MONGODB_URL	MongoDB connection string
Variable	Description
:---	:---
MONGODB_URL	MongoDB connection string
NESSIE_API_KEY	Capital One Nessie API Key
GEMINI_KEY	Google AI Studio Key
GEMINI_KEY	Google AI Studio Key
ELEVEN_LABS_API_KEY	ElevenLabs API Key
VONAGE_APP_ID	Vonage Application ID
VONAGE_FROM_NUMBER	Vonage Virtual Number

---

📸 Screenshots

---

Built with ❤️ (and a bit of passive aggression) for roommates everywhere. | VONAGE_APP_ID | Vonage Application ID | | VONAGE_FROM_NUMBER | Vonage Virtual Number |

---