Developer Setup

Get the development environment running in under 5 minutes.

Prerequisites

Docker Desktop - with Docker Compose V2
Node.js 20+ - for frontend development
Go 1.22+ - for backend development (optional if only working on frontend)
Make - for running build commands
Git - for version control

Clone and Start Services

1. Clone the repository

git clone <repository-url>
cd invoice-pro

2. Start all backend services

docker compose up -d

This starts: PostgreSQL, Redis, Backend, Envoy, Go Extractor, OCR Service, Grafana, Loki

3. Verify services are healthy

# Check all containers are running
docker compose ps

# Watch backend logs for startup messages
docker compose logs -f backend

Wait until you see: ✓ gRPC server listening on :50052

Start Frontend

Important: The frontend runs locally with Node.js, not in Docker. This enables hot reload during development.

cd frontend
npm install
npm run dev

Access Points

http://localhost:3000 - Frontend app
http://localhost:3001 - Grafana (admin/admin)
http://localhost:8080 - REST API
http://localhost:6060 - Go pprof (profiling)

Create a Test Account

Visit http://localhost:3000/register to create an account.

In development mode, email verification is skipped. You can register with any email and start using the app immediately.

Environment Variables

Create backend/.env for optional services:

# Currency conversion (ExchangeRate-API)
EXCHANGE_RATE_API_KEY=your_api_key

# AWS S3 for file uploads
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_REGION=us-east-1
S3_BUCKET_NAME=your_bucket

# Email sending (SparkPost)
SPARKPOST_API_KEY=your_key
EMAIL_FROM_ADDRESS=noreply@yourdomain.com

# Slack integration
SLACK_CLIENT_ID=your_client_id
SLACK_CLIENT_SECRET=your_client_secret

# AI features (OpenAI)
OPENAI_API_KEY=your_key

All environment variables are optional. The app works without them, but certain features (FX rates, file uploads, emails, AI) will be disabled.

Default Database Configuration

Host: localhost (or postgres from within Docker)
Port: 5432
Database: postgres
User: postgres
Password: postgres

Connect to database

docker compose exec postgres psql -U postgres -d postgres

Common Commands

Docker

# Start all services
docker compose up -d

# Stop all services
docker compose down

# Rebuild backend after Go changes
docker compose up -d --build backend

# View logs
docker compose logs -f backend

# Reset database (removes all data)
docker compose down -v

Frontend

cd frontend

npm run dev      # Development server
npm run build    # Production build
npm run lint     # Run ESLint

Proto generation

# After modifying .proto files
make proto

# This generates:
# - backend/proto/*.pb.go
# - backend/proto/*.pb.gw.go
# - frontend/src/gen/*.ts

Troubleshooting

Backend won't start

Check if PostgreSQL and Redis are healthy:

docker compose ps
docker compose logs postgres
docker compose logs redis

Port already in use

Stop conflicting services or change ports in docker-compose.yml:

# Find what's using a port
lsof -i :5432

# Kill the process
kill -9 <PID>

Frontend can't connect to backend

Ensure Envoy is running and the backend is healthy. Check docker compose logs envoy

Fresh start

Remove all containers and volumes:

docker compose down -v
docker compose up -d

Technical docs Architecture