BillBuddy - Invoice Management System

A production-ready, backend-centric invoice management system built with FastAPI and React. Features secure CRUD operations, automated email reminders, Stripe payment integration with INR support, and CSV-based financial reporting.

🚀 Features

Invoice Management

• Secure CRUD Operations: Create, read, update, and delete invoices with JWT-based authentication
• Real-time Status Tracking: Track invoice status (unpaid, paid, overdue)
• Client Management: Associate invoices with client information

Payment Processing

• Stripe Integration: PCI-compliant payment processing via Stripe Checkout
• Multi-currency Support: Configured for INR (Indian Rupee) transactions
• Webhook Handling: Real-time payment status updates via Stripe webhooks

Automation & Reporting

• Email Reminders: Automated reminder scheduling for overdue invoices using Celery
• CSV Export: Generate financial reports in CSV format for accounting
• Background Tasks: Asynchronous task processing with Redis backing

Production Infrastructure

• Docker Deployment: Containerized application with Docker Compose
• HTTPS Reverse Proxy: Traefik-based SSL/TLS termination
• CI/CD Ready: GitHub Actions workflow for automated testing and deployment
• Database: PostgreSQL with Alembic migrations

🛠️ Tech Stack

Layer	Technology
Backend	FastAPI, Python 3.10, SQLModel, Pydantic
Frontend	React, TypeScript, Vite, Chakra UI
Database	PostgreSQL, Alembic
Payments	Stripe API, Webhooks
Task Queue	Celery, Redis
Infrastructure	Docker, Traefik, Nginx

📦 Quick Start

Prerequisites

• Docker & Docker Compose
• Stripe Account (for payments)

Installation

1. Clone the repository

   git clone https://github.com/yourusername/billbuddy.git
   cd billbuddy

2. Configure environment

   cp .env.example .env
   # Edit .env with your Stripe keys and other settings

3. Start the application

   docker compose up -d

4. Access the application

   • Frontend: http://localhost:5173
   • API Docs: http://localhost:8000/docs

Default Login

• Email: admin@example.com
• Password: changethis

📁 Project Structure

├── backend/
│   ├── app/
│   │   ├── api/routes/      # API endpoints (invoices, payments, reports)
│   │   ├── core/            # Configuration, security, database
│   │   └── models/          # SQLModel schemas
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── routes/          # Page components
│   │   └── client/          # API services
│   └── Dockerfile
├── compose.yml              # Docker Compose configuration
└── compose.traefik.yml      # Production HTTPS setup

🔧 Configuration

Environment Variables

Variable	Description
STRIPE_SECRET_KEY	Stripe API secret key
STRIPE_PUBLISHABLE_KEY	Stripe publishable key
STRIPE_WEBHOOK_SECRET	Stripe webhook signing secret
POSTGRES_PASSWORD	Database password
SECRET_KEY	JWT signing key

Production Deployment

For production deployment with HTTPS:

docker compose -f compose.yml -f compose.traefik.yml up -d

📊 API Endpoints

Method	Endpoint	Description
POST	/api/v1/invoices/	Create invoice
GET	/api/v1/invoices/	List invoices
DELETE	/api/v1/invoices/{id}	Delete invoice
POST	/api/v1/invoices/{id}/remind	Schedule reminder
POST	/api/v1/payments/create-checkout/{id}	Create Stripe checkout
GET	/api/v1/reports/invoices/csv	Export CSV report

🧪 Testing

# Run backend tests
docker compose exec backend pytest

# Run with coverage
docker compose exec backend pytest --cov=app

📄 License

MIT License - see LICENSE file for details.

👤 Author

Developed as a full-stack invoice management solution demonstrating:

• Backend API development with FastAPI
• Third-party payment integration (Stripe)
• Task queue implementation (Celery/Redis)
• Production deployment with Docker