💰 Penny - AI-Powered Expense Tracker

Penny is a modern, AI-powered expense tracking application built with Next.js, Firebase, and Gemini AI. Track expenses, manage budgets, collaborate in groups, and get intelligent insights - all with a beautiful, mobile-first interface.

✨ Features

🤖 AI-Powered Expense Tracking

Natural Language Input: Describe expenses in plain English
Smart Categorization: AI automatically categorizes expenses
Receipt OCR: Upload receipts and extract details automatically
Conversational Interface: Chat with Penny to manage your finances

💰 Smart Budgeting

Personal & Group Budgets: Set budgets at individual or group level
Real-time Tracking: Live budget usage with visual indicators
Smart Alerts: Get notified at 75%, 90%, and 100% thresholds
Budget Impact Preview: See impact before saving expenses

👥 Group Expense Management

Shared Groups: Track expenses with family, roommates, or teams
Role-Based Permissions: Owner, Admin, Member roles with granular controls
Group Invitations: Invite members via email
Group Budgets: Set and track budgets for the entire group

🔔 Smart Notifications

Real-time Updates: Get notified of group activity instantly
Budget Alerts: Never exceed your budget unknowingly
Smart Grouping: Similar notifications grouped to reduce noise
Customizable Settings: Control what you're notified about

📊 Analytics & Insights

Dashboard: Visual overview of spending patterns
Category Breakdown: See where your money goes
Trends: Track spending over time
Group Analytics: Compare personal vs group spending

🔐 Advanced Security

Passkey Authentication: Passwordless login with biometrics
Firebase Auth: Secure authentication with email/password
Row-Level Security: Firestore rules ensure data isolation
Admin Console: Monitoring and management tools

📱 Progressive Web App (PWA)

Offline Support: Work without internet connection
Mobile-First Design: Optimized for mobile devices
Push Notifications: Native-like notification experience
Install to Home Screen: Works like a native app

🚀 Quick Start

Prerequisites

Node.js 20+
Firebase account
Google Gemini API key (for AI features)

1. Clone and Install

git clone https://github.com/sarathfrancis90/penny.git
cd penny
npm install

2. Configure Environment

cp env.example .env.local
# Edit .env.local with your Firebase and Gemini API keys

3. Deploy Database Configuration

firebase login
firebase deploy --only firestore

4. Run Development Server

npm run dev

Open http://localhost:3000 to see the app!

📚 Documentation

🤖 Agentic Engineering

Agent Guide - Required reading order and non-negotiable agent rules
Agent Documentation Index - Complete agent operating manual
Complete File Map - Generated inventory covering tracked and nonignored working-tree files

🗄️ Database

Database Schema - Complete database structure
DevOps Guide - CI/CD and best practices
Setup Complete - Infrastructure overview
Firestore Rules - Security rules deployment
Permission Fixes - Troubleshooting

🎨 Features

🚢 Deployment

Deployment Guide - Full deployment instructions
Quick Start - Get started in 5 minutes
Firebase Setup - Firebase configuration
Gemini Setup - AI integration
PWA Setup - Progressive Web App
Vercel Deployment - Vercel-specific fixes

🧪 Testing

Testing Guide - Comprehensive testing strategy
Groups Testing - Group features testing
Notifications Testing - Notification testing
Default Group Verification

👨‍💼 Admin

Admin Console - Admin dashboard setup
Costs & Monitoring - Cost tracking
Admin Updates - Latest admin features

🏗️ Architecture

Tech Stack

Frontend: Next.js 15, React 18, TypeScript
Backend: Next.js API Routes, Firebase Admin SDK
Database: Cloud Firestore (NoSQL)
Storage: Firebase Storage (receipts/images)
AI: Google Gemini 1.5 Pro
Authentication: Firebase Auth + Passkeys
Styling: Tailwind CSS, Shadcn UI
State Management: React Hooks, Firestore Real-time
PWA: Workbox, Service Workers

Project Structure

penny/
├── database/                   # Database configuration
│   ├── firestore.rules        # Security rules
│   ├── firestore.indexes.json # Query indexes
│   └── storage.rules          # Storage rules
├── docs/                       # Documentation
│   ├── admin/                 # Admin guides
│   ├── database/              # Database docs
│   ├── deployment/            # Deployment guides
│   ├── features/              # Feature documentation
│   └── testing/               # Testing guides
├── public/                     # Static assets
│   └── manifest.json          # PWA manifest
├── scripts/                    # Utility scripts
├── src/
│   ├── app/                   # Next.js app router
│   │   ├── api/              # API routes
│   │   ├── admin-console/    # Admin dashboard
│   │   ├── budgets/          # Budget management
│   │   ├── groups/           # Group management
│   │   └── settings/         # User settings
│   ├── components/            # React components
│   │   ├── budgets/          # Budget components
│   │   ├── chat/             # Chat interface
│   │   ├── groups/           # Group components
│   │   ├── notifications/    # Notification UI
│   │   └── ui/               # Shadcn UI components
│   ├── hooks/                 # Custom React hooks
│   └── lib/                   # Utilities & services
│       ├── services/         # Business logic
│       └── types/            # TypeScript types
└── .github/
    └── workflows/             # CI/CD pipelines

🔧 Development

Available Scripts

npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint
npm run type-check   # Run TypeScript compiler

Database Management

# Deploy database configuration
firebase deploy --only firestore

# Deploy specific components
firebase deploy --only firestore:rules
firebase deploy --only firestore:indexes
firebase deploy --only storage

# Start emulators for local testing
firebase emulators:start

Environment Variables

See env.example for required environment variables:

Firebase configuration
Gemini API key
JWT secret for passkeys
NextAuth configuration

🚀 Deployment

Automated CI/CD

Every push to main automatically deploys database configuration via GitHub Actions.

Triggers on changes to:

database/firestore.rules
database/firestore.indexes.json
database/storage.rules
firebase.json

Manual Deployment

# Deploy everything
npm run build
vercel --prod

# Deploy only database
firebase deploy --only firestore

See Deployment Guide for detailed instructions.

📊 Monitoring

Firebase Console

Firestore Usage: Monitor read/write operations
Storage Usage: Track file storage
Auth Users: Monitor active users
Performance: Track query performance

Admin Console

Access at /admin-console for:

User management
Cost monitoring
System health
Analytics

See Admin Console Guide for details.

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow TypeScript best practices
Write clear commit messages
Add tests for new features
Update documentation
Ensure CI/CD passes

📝 License

🙏 Acknowledgments

Next.js Team - Amazing React framework
Firebase - Backend infrastructure
Google Gemini - AI capabilities
Shadcn - Beautiful UI components
Vercel - Hosting and deployment

📞 Support

Documentation: Check the docs folder
Issues: Open a GitHub issue
Questions: Contact the maintainer

🔗 Links

Live App: https://penny-amber.vercel.app
Firebase Console: https://console.firebase.google.com/project/penny-f4acd
GitHub Actions: https://github.com/sarathfrancis90/penny/actions

Built with ❤️ by Sarath Francis

Making expense tracking effortless with AI

Name		Name	Last commit message	Last commit date
.claude		.claude
.cursor/rules		.cursor/rules
.githooks		.githooks
.github		.github
.xcodebuildmcp		.xcodebuildmcp
apps/api/src		apps/api/src
database		database
docs		docs
mobile		mobile
packages/shared/src		packages/shared/src
public		public
screenshots		screenshots
scripts		scripts
src		src
.dockerignore		.dockerignore
.firebaserc		.firebaserc
.gcloudignore		.gcloudignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
DIALOGS_AUDIT_REPORT.md		DIALOGS_AUDIT_REPORT.md
Dockerfile.api		Dockerfile.api
FORMS_AUDIT_REPORT.md		FORMS_AUDIT_REPORT.md
PRIVACY.md		PRIVACY.md
README.md		README.md
SHARED_COMPONENTS_AUDIT_COMPLETE.md		SHARED_COMPONENTS_AUDIT_COMPLETE.md
UI_CONTROLS_CONSISTENCY_AUDIT.md		UI_CONTROLS_CONSISTENCY_AUDIT.md
UI_UX_AUDIT_REPORT.md		UI_UX_AUDIT_REPORT.md
UI_UX_CONSISTENCY_COMPLETE.md		UI_UX_CONSISTENCY_COMPLETE.md
UI_UX_STANDARDIZATION_COMPLETE.md		UI_UX_STANDARDIZATION_COMPLETE.md
UI_UX_STANDARDIZATION_PHASE2_COMPLETE.md		UI_UX_STANDARDIZATION_PHASE2_COMPLETE.md
cloudbuild.api.yaml		cloudbuild.api.yaml
components.json		components.json
env.example		env.example
eslint.config.mjs		eslint.config.mjs
firebase.json		firebase.json
next.config.ts		next.config.ts
osv-scanner.toml		osv-scanner.toml
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
sentry.client.config.ts		sentry.client.config.ts
sentry.edge.config.ts		sentry.edge.config.ts
sentry.server.config.ts		sentry.server.config.ts
tsconfig.api.json		tsconfig.api.json
tsconfig.json		tsconfig.json
vercel.json		vercel.json
vitest.config.ts		vitest.config.ts
vitest.database.config.ts		vitest.database.config.ts

Latest commit

History

Folders and files

Repository files navigation