A modern full-stack invoice management system with PDF generation
Invoice Generator is a production-ready application demonstrating modern web development practices with a Go backend and Next.js frontend. Create, manage, and generate professional PDF invoices with customizable templates.
- Invoice Management — Create, view, and manage invoices with detailed line items
- PDF Generation — Professional PDF output using wkhtmltopdf
- Custom Templates — Upload and manage your own HTML invoice templates
- User Authentication — Secure JWT-based authentication system
- Multi-Currency Support — Handle invoices in different currencies
- RESTful API — Clean API design with protected and public endpoints
- Database Migrations — Version-controlled schema using golang-migrate
- Caching Layer — Redis integration for improved performance
- Docker Support — Full Docker Compose setup for easy deployment
- Development Scripts — Comprehensive tooling for local development
| Layer | Technology |
|---|---|
| Backend | Go 1.23 + Gin Framework |
| Frontend | Next.js 15 + React 19 + TypeScript |
| Database | PostgreSQL 15 |
| Cache | Redis 7 |
| Styling | Tailwind CSS + shadcn/ui |
| Auth | JWT (golang-jwt/jwt) |
| wkhtmltopdf |
Perfect for: Quick evaluation, production-like environment, team consistency
# 1. Configure environment
cp .env.example .env
# Edit .env with your database credentials and JWT secret
# 2. Start everything
docker-compose up --build -d
# 3. Access the application
# Frontend: http://localhost:3000
# Backend: http://localhost:8080Perfect for: Active development, debugging, faster iteration
# 1. One-time setup (installs dependencies)
chmod +x scripts/*.sh
./scripts/dev-setup.sh
# 2. Start all services
./scripts/dev-start.sh
# 3. Access the application
# Frontend: http://localhost:3000
# Backend: http://localhost:8080
# 4. Check status
./scripts/dev-check.sh
# 5. Stop when done
./scripts/dev-stop.shinvoice-generator-go/
├── invoice-generator-backend/ # Go API server
│ ├── api/ # HTTP handlers and routes
│ ├── cmd/ # Application entry point
│ ├── config/ # Configuration loading
│ ├── migrations/ # Database migrations
│ ├── models/ # Domain models
│ ├── pdf/ # PDF generation
│ ├── storage/ # Data access layer
│ └── utils/ # JWT, auth, helpers
│
├── invoice-generator-frontend/ # Next.js application
│ ├── src/app/ # App Router pages
│ ├── components/ # React components
│ └── public/ # Static assets
│
├── scripts/ # Development helper scripts
│ ├── dev-setup.sh # One-time setup
│ ├── dev-start.sh # Start all services
│ ├── dev-stop.sh # Stop all services
│ └── dev-check.sh # Check service status
│
├── docker-compose.yml # Docker orchestration
├── .env.example # Environment template
└── README.md # This file
Create a .env file in the project root:
# Database
DB_PASSWORD=your_secure_password_here
# JWT Authentication
JWT_SECRET=your_jwt_secret_change_this_in_production
# CORS Configuration
CORS_ALLOWED_ORIGINS=http://localhost:3000
# API URL (for frontend)
NEXT_PUBLIC_API_URL=http://localhost:8080Important: Change default passwords and secrets before deploying to production!
# Start work
./scripts/dev-start.sh
# Check everything is running
./scripts/dev-check.sh
# View logs
./scripts/dev-logs.sh
tail -f logs/backend.log
tail -f logs/frontend.log
# Restart after backend changes
./scripts/dev-restart.sh
# Stop work
./scripts/dev-stop.shcd invoice-generator-backend
# Run tests
go test ./...
# Format code
go fmt ./...
# Build binary
go build -o invoice-generator ./cmd
# Run backend only
go run ./cmdcd invoice-generator-frontend
# Install dependencies
npm install
# Start dev server (with hot reload)
npm run dev
# Build for production
npm run build
# Lint code
npm run lint# Access PostgreSQL
psql -U invoice_user -d invoice_db -h localhost
# Run migrations
cd invoice-generator-backend
migrate -database "$POSTGRES_URL" -path migrations up
# Rollback migration
migrate -database "$POSTGRES_URL" -path migrations down 1POST /api/register— Create new user accountPOST /api/login— Authenticate and receive JWT token
POST /api/invoices— Create new invoiceGET /api/invoices/:id— Retrieve invoice detailsPOST /api/templates— Upload custom invoice templateGET /api/templates— List all templates
Authentication: Include JWT token in header:
Authorization: Bearer <your_jwt_token>
- Local Development Guide — Detailed setup and troubleshooting for WSL/Linux
- Docker Guide — Complete Docker setup and operations
- Scripts Reference — Full reference for all development scripts
- Claude Code Guide — Architecture and guidance for AI assistants
# Check what's using ports
lsof -i :8080 # Backend
lsof -i :3000 # Frontend
# Kill processes
lsof -ti:8080 | xargs kill -9# Check PostgreSQL status
sudo service postgresql status
# Restart PostgreSQL
sudo service postgresql restart
# Test connection
psql -U invoice_user -d invoice_db -h localhost# View logs
cat logs/backend.log
# Check dependencies
cd invoice-generator-backend
go mod download
go mod tidy# View logs
cat logs/frontend.log
# Clear cache and reinstall
cd invoice-generator-frontend
rm -rf node_modules .next
npm installFor more detailed troubleshooting, see DEV_README.md.
See the LICENSE file for details.
Built with Go and Next.js • Designed for developers who value clean architecture and modern tooling