GitHub - HA2345567/SmartInvoice: SmartInvoice is a modern invoicing web application designed to streamline billing for freelancers and small businesses.

AI-powered invoice management built for modern freelancers & businesses.

Create, send, and track professional invoices — with AI that learns your workflow.

🚀 Get Started · ✨ Features · 📖 API Docs · 🚢 Deploy

🧭 Overview

SmartInvoice is a production-ready SaaS application for creating, managing, and sending professional invoices. It blends a sleek Spotify-inspired dark UI with AI-powered features — from smart auto-fill to payment prediction — making it faster and smarter than traditional invoicing tools.

Built for: Freelancers, agencies, consultants, and small businesses that need a professional invoicing solution without the enterprise overhead.

✨ Features

🧾 Core Invoicing

Feature	Description
Invoice Management	Create, edit, send, duplicate, and archive invoices
Smart Numbering	Auto-incremented invoice numbers with custom prefixes
PDF Generation	Branded, pixel-perfect PDF export via Puppeteer & jsPDF
Multi-Currency	Support for global currencies with per-client preferences
Tax & Discounts	GST/VAT calculations with line-item and invoice-level discounts
Payment Tracking	Mark invoices as paid, track payment method & date

🤖 AI-Powered Features

Feature	Description
AI Chatbot Assistant	Floating conversational interface — create invoices via chat
Smart Suggestions	Auto-complete line items based on client history (Gemini AI)
Description Enhancer	Rewrite item descriptions in Formal or Friendly tone
Payment Predictor	Cash-flow forecast with confidence intervals
Expense Categorizer	AI categorizes uploaded receipts automatically

📊 Analytics & Reporting

Revenue insights with interactive charts (Recharts)
Invoice status breakdown — Draft, Sent, Paid, Overdue
Cash-flow forecast dashboard widget
CSV export for accounting tools

👥 Client Management

Full client database with company, address, GST number, currency
Per-client invoice history and tracking
Smart client search with fuzzy matching

📧 Automation

Automated email delivery via Nodemailer (Gmail SMTP) or Resend
Configurable payment reminder sequences
Reminder history tracking per invoice

🔐 Security

JWT-based authentication with bcryptjs password hashing
ALTCHA CAPTCHA integration on auth flows
Secure HTTP-only cookie sessions
Input validation with Zod schemas

🛠 Tech Stack

Frontend

Layer	Technology
Framework	Next.js 14 (App Router)
Language	TypeScript 5.2
UI Components	Radix UI + shadcn/ui
Styling	Tailwind CSS + custom dark theme
Animations	Framer Motion
Charts	Recharts
Forms	React Hook Form + Zod
Icons	Lucide React

Backend

Layer	Technology
Runtime	Node.js ≥ 18
Database	PostgreSQL via Neon serverless
Database Client	`@neondatabase/serverless`
Auth	JWT (`jsonwebtoken`) + `bcryptjs`
Email	Nodemailer (SMTP) + Resend API
PDF	Puppeteer + jsPDF + html2canvas
AI	Google Gemini (`@google/generative-ai`)
Payments	Razorpay SDK

Infrastructure

Layer	Technology
Hosting	Vercel (recommended)
Database	Neon (serverless Postgres)
Package Manager	Bun

📁 Project Structure

SmartInvoice/
├── app/
│   ├── api/                        # API route handlers
│   │   ├── auth/                   #   Login, signup, logout
│   │   ├── invoices/               #   CRUD + PDF + email
│   │   ├── clients/                #   Client management
│   │   ├── reminders/              #   Reminder scheduling & sending
│   │   ├── analytics/              #   Revenue & stats
│   │   ├── ai/                     #   AI chatbot & suggestions
│   │   ├── expenses/               #   Expense tracking & AI categorization
│   │   ├── export/                 #   CSV export
│   │   ├── proposals/              #   Proposal management
│   │   ├── tax/                    #   Tax calculation
│   │   └── upload/                 #   File upload
│   ├── auth/                       # Auth pages (login, signup)
│   ├── dashboard/                  # Protected dashboard routes
│   │   ├── agent/                  #   AI agent interface
│   │   ├── analytics/              #   Revenue analytics
│   │   ├── clients/                #   Client list & detail
│   │   ├── create/                 #   Invoice creation wizard
│   │   ├── expenses/               #   Expense management
│   │   ├── invoices/               #   Invoice list & detail
│   │   ├── proposals/              #   Proposals
│   │   ├── reminders/              #   Reminder settings
│   │   ├── reports/                #   Financial reports
│   │   ├── settings/               #   User & business settings
│   │   ├── tax/                    #   Tax dashboard
│   │   └── components/             #   Shared dashboard components
│   ├── globals.css                 # Global styles & design tokens
│   ├── layout.tsx                  # Root layout
│   └── page.tsx                    # Landing page
├── components/
│   ├── ai/                         # AI chatbot & suggestion UI
│   ├── invoice/                    # Invoice form & preview
│   ├── invoices/                   # Invoice list components
│   ├── security/                   # CAPTCHA & security
│   └── ui/                         # Base UI primitives (shadcn)
├── lib/
│   ├── database.ts                 # DB queries & type interfaces
│   ├── auth.ts                     # JWT helpers
│   ├── ai-agent.ts                 # AI agent orchestration
│   ├── gemini.ts                   # Gemini AI client
│   ├── smart-suggestions.ts        # AI suggestion engine
│   ├── email-service.ts            # Email sending logic
│   ├── pdf-generator.ts            # PDF generation
│   ├── invoice-generator.ts        # Invoice number logic
│   ├── payment-service.ts          # Razorpay integration
│   ├── reminder-service.ts         # Reminder scheduling
│   └── error-handler.ts            # Centralized error handling
├── types/                          # Shared TypeScript types
├── hooks/                          # Custom React hooks
├── contexts/                       # React context providers
├── public/                         # Static assets
└── supabase/                       # Database migration files

🚀 Quick Start

Prerequisites

Node.js ≥ 18.0.0
Bun (recommended) or npm ≥ 8.0.0
PostgreSQL database — local or Neon for cloud

1. Clone the Repository

git clone https://github.com/your-username/SmartInvoice.git
cd SmartInvoice

2. Install Dependencies

bun install
# or
npm install

3. Configure Environment Variables

cp .env.local.example .env.local
# Fill in your values — see Environment Variables section below

4. Set Up the Database

Run the SQL migration files against your PostgreSQL instance:

psql -d your_database_url -f supabase/migrations/001_initial.sql

Or paste the SQL directly in the Supabase / Neon dashboard query editor.

5. Start the Development Server

bun dev
# or
npm run dev

Open http://localhost:3000 — the app is live! 🎉

🔑 Environment Variables

Create a .env.local file at the project root:

# ─── Application ──────────────────────────────────────────────
NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:3000

# ─── Database (Required) ──────────────────────────────────────
DATABASE_URL=postgresql://username:password@host:5432/smartinvoice

# ─── Authentication (Required) ────────────────────────────────
# Generate: openssl rand -base64 32
JWT_SECRET=your-super-secret-jwt-key-min-32-chars

# ─── Email via SMTP (Optional) ────────────────────────────────
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-specific-password
EMAIL_FROM=noreply@yourdomain.com

# ─── Email via Resend (Alternative) ──────────────────────────
RESEND_API_KEY=re_your_api_key

# ─── Google Gemini AI (Required for AI features) ──────────────
GEMINI_API_KEY=your-gemini-api-key

# ─── Razorpay (Optional — payment links) ─────────────────────
RAZORPAY_KEY_ID=rzp_live_your_key
RAZORPAY_KEY_SECRET=your_razorpay_secret

Gmail Tip: Create an App Password — do not use your main account password.

📖 API Reference

All routes are under /api/. Protected routes require a valid JWT passed as a Bearer token in the Authorization header, or as a session cookie.

🔐 Authentication

`POST /api/auth/signup`

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "password": "securepassword123",
  "company": "Doe Studios"
}

`POST /api/auth/login`

{
  "email": "jane@example.com",
  "password": "securepassword123"
}

`POST /api/auth/logout`

Clears the session cookie. No body required.

🧾 Invoices

Method	Endpoint	Description
`GET`	`/api/invoices`	List all invoices
`POST`	`/api/invoices`	Create a new invoice
`GET`	`/api/invoices/[id]`	Get invoice by ID
`PUT`	`/api/invoices/[id]`	Update an invoice
`DELETE`	`/api/invoices/[id]`	Delete an invoice
`POST`	`/api/invoices/[id]/send`	Send invoice via email
`GET`	`/api/invoices/[id]/pdf`	Download as PDF

Create Invoice — Example Payload:

{
  "clientName": "Acme Corp",
  "clientEmail": "billing@acme.com",
  "clientAddress": "123 Main St, New York, NY 10001",
  "items": [
    { "description": "Web Design", "quantity": 1, "rate": 2500 },
    { "description": "SEO Setup", "quantity": 3, "rate": 150 }
  ],
  "taxRate": 18,
  "discountRate": 5,
  "dueDate": "2026-09-01",
  "notes": "Thank you for your business!",
  "currency": "USD"
}

👥 Clients

Method	Endpoint	Description
`GET`	`/api/clients`	List all clients
`POST`	`/api/clients`	Create a client
`PUT`	`/api/clients/[id]`	Update client
`DELETE`	`/api/clients/[id]`	Delete client

📊 Analytics

Method	Endpoint	Description
`GET`	`/api/analytics`	Revenue summary & KPIs
`GET`	`/api/analytics/cashflow`	Cash-flow forecast data

🤖 AI

Method	Endpoint	Description
`POST`	`/api/ai/chat`	Send message to AI assistant
`GET`	`/api/suggestions`	Smart line-item suggestions

📧 Reminders

Method	Endpoint	Description
`GET`	`/api/reminders`	List reminder config
`POST`	`/api/reminders/send`	Manually trigger reminders

📤 Export

Method	Endpoint	Description
`GET`	`/api/export/invoices`	Export invoices as CSV
`GET`	`/api/export/expenses`	Export expenses as CSV

🚢 Deployment

▲ Vercel (Recommended — ~5 min)

Push your repository to GitHub.
Go to vercel.com → New Project → import your repo.
Add all environment variables in the Vercel dashboard under Settings → Environment Variables.
Click Deploy.

# Or via CLI
npm i -g vercel
vercel --prod

🚂 Railway (~5 min)

npm i -g @railway/cli
railway login
railway init
railway up

🐳 Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

docker build -t smartinvoice .
docker run -p 3000:3000 --env-file .env.local smartinvoice

🖥 Manual (nginx + PM2)

npm run build
pm2 start npm --name "smartinvoice" -- start
# Set up nginx as reverse proxy on port 3000

🔒 Security

SmartInvoice follows security best practices out of the box:

Area	Implementation
Authentication	JWT tokens, configurable expiry, HTTP-only cookies
Passwords	`bcryptjs` hashing with ≥ 10 salt rounds
Bot Protection	ALTCHA CAPTCHA on registration
Input Validation	Zod schemas on all API endpoints
Secrets	No sensitive values in client bundle
Transport	HTTPS enforced in production

Pre-Launch Checklist

Rotate JWT_SECRET — openssl rand -base64 32
Set NODE_ENV=production
Enable SSL on the database connection
Use a strong, unique database password
Configure CORS for your production domain
Enable rate limiting on auth endpoints
Set up automated database backups

📜 Available Scripts

Command	Description
`bun dev`	Start the development server
`bun run build`	Build for production
`bun start`	Start the production server
`bun run lint`	Run ESLint
`bun run type-check`	TypeScript type check (`tsc --noEmit`)
`bun run clean`	Clear `.next` build cache
`bun run dev:clean`	Clean + start dev server
`npm run security-audit`	Run `npm audit` for vulnerabilities

🔧 Troubleshooting

Database Connection Fails

Verify DATABASE_URL format: postgresql://user:pass@host:5432/dbname
If using Neon, use the pooled connection string
Check that your IP is allowlisted in the database firewall settings

Emails Not Sending

For Gmail: use an App Password, not your account password
Ensure EMAIL_PORT=587 and EMAIL_SECURE=false for STARTTLS
Test the mail config: GET /api/test-email

AI Features Not Working

Verify GEMINI_API_KEY is valid in Google AI Studio
Check API quota limits on your Google Cloud project
AI features gracefully degrade — the app is fully functional without an AI key

PDF Generation Fails

On Vercel/serverless: jsPDF mode is used automatically (no Puppeteer)
On a VPS: install Chromium dependencies
```
apt-get install -y chromium libgbm-dev
```

Build Errors

# Clear all caches and reinstall
bun run clean
rm -rf node_modules
bun install
bun run build

🤝 Contributing

Contributions are welcome and appreciated! Please follow these steps:

Fork this repository
Create a feature branch: git checkout -b feat/your-feature

Commit your changes using conventional commits:

feat:     New feature
fix:      Bug fix
docs:     Documentation only
refactor: Code refactoring
chore:    Build/tooling updates

Push your branch: git push origin feat/your-feature
Open a Pull Request with a clear description of what changed and why

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Built with ❤️ using Next.js, TypeScript, and a lot of ☕

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
app		app
components		components
contexts		contexts
hooks		hooks
lib		lib
public		public
scripts		scripts
supabase/migrations		supabase/migrations
types		types
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
AI_FEATURES_PLAN.md		AI_FEATURES_PLAN.md
PRODUCTION_READY.md		PRODUCTION_READY.md
README.md		README.md
SETUP.md		SETUP.md
bun.lock		bun.lock
components.json		components.json
deploy.sh		deploy.sh
deployment-checklist.md		deployment-checklist.md
next.config.js		next.config.js
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation