Finsolvz Backend is a comprehensive financial solutions management system built with Go and Clean Architecture principles. The system provides robust APIs for user management, company management, and financial report type management with role-based access control.
- π JWT Authentication & Authorization - Secure login with role-based access control (SUPER_ADMIN, ADMIN, CLIENT)
- π₯ User Management - Complete CRUD operations with role management and password reset functionality
- π’ Company Management - Multi-tenant company management with user associations
- π Report Type Management - Manage different types of financial reports
- π Clean Architecture - Modular design with clear separation of concerns (Domain, Service, Repository, Handler)
- π Structured Logging - Comprehensive logging for debugging and monitoring
- π§ Email Service - Automated email notifications for password reset
- π³ Docker Ready - Containerized application for easy deployment
- βοΈ GCP Compatible - Ready for Google Cloud Platform deployment
- π Interactive API Documentation - Swagger UI for testing and documentation
- Language: Go 1.22.4
- Web Framework: Gorilla Mux
- Database: MongoDB
- Authentication: JWT (golang-jwt/jwt/v5)
- Password Hashing: bcrypt
- Validation: go-playground/validator/v10
- CORS: rs/cors
- Containerization: Docker
- Email Service: SMTP (Gmail)
- Documentation: OpenAPI 3.0 + Swagger UI
- Windows with WSL2 (Ubuntu 20.04+ recommended)
- Go 1.22.4+ installed in WSL
- Docker installed and running in WSL
- MongoDB (local installation or MongoDB Atlas)
- Git for version control
- Go 1.22.4+
- Docker
- MongoDB
- Git
- Go 1.22.4+
- Docker Desktop
- MongoDB
- Git
# Prerequisites: Go 1.22+, MongoDB
go mod download
cp .env.example .env # Configure your environment
go run cmd/server/main.go- Push to
mainβ Auto-deploy via GitHub Actions - Manual testing:
make test - Local build:
make build
β 70-80% faster response times
- Jakarta region deployment (20-80ms from Indonesia)
- Smart caching system (3-5 min TTL)
- Optimized database queries & indexes
- Response compression (60-70% size reduction)
- Free Tier optimized (512Mi memory, 0-3 instances)
# Copy environment template
cp .env.example .env
# Edit configuration
nano .envExample .env configuration:
GREETING="β¨ Finsolvz Backend API β¨"
PORT=8787
MONGO_URI=mongodb://localhost:27017/Finsolvz
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
APP_ENV=development
# Email Configuration (for password reset)
NODEMAILER_EMAIL=[email protected]
NODEMAILER_PASS=your-app-password# Install Go modules
go mod tidy
# Verify dependencies
go mod verifyOption A: Local MongoDB
# Ubuntu/WSL
sudo apt install -y mongodb
sudo systemctl start mongodb
sudo systemctl enable mongodbOption B: MongoDB Atlas (Cloud)
# Create free cluster at https://cloud.mongodb.com
# Update MONGO_URI in .env with connection stringOption C: Docker MongoDB
# Run MongoDB in Docker
docker run -d --name mongo-finsolvz -p 27017:27017 mongo:7.0# In WSL or your development environment
cd ~/workspace/finsolvz-backend
# Run the application
go run cmd/server/main.go
# Or build and run
go build -o bin/finsolvz-backend cmd/server/main.go
./bin/finsolvz-backendBackend will be available at: http://localhost:8787
# Create default admin account
go run create_admin.go
# Output will show:
# β
Admin created!
# Email: [email protected]
# Password: admin123# Ensure you're in the project directory
cd ~/workspace/finsolvz-backend
# Clean up any existing Swagger containers
docker stop $(docker ps -q --filter "ancestor=swaggerapi/swagger-ui") 2>/dev/null || true
docker rm $(docker ps -aq --filter "ancestor=swaggerapi/swagger-ui") 2>/dev/null || true
# Start Swagger UI (will auto-find available port)
# Try port 8081 first, then 8082, 8083, etc. if busy
docker run -d --name swagger-finsolvz -p 8082:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $(pwd)/api:/app swaggerapi/swagger-ui
# Verify container is running
docker ps
# Check logs if needed
docker logs swagger-finsolvz# In PowerShell (as Administrator)
cd C:\path\to\finsolvz-backend
# Start Swagger UI
docker run -d --name swagger-finsolvz -p 8082:8080 -e SWAGGER_JSON=/app/openapi.yaml -v "${PWD}/api:/app" swaggerapi/swagger-ui# If port 8082 is busy, try different ports
docker run -d --name swagger-finsolvz -p 8083:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $(pwd)/api:/app swaggerapi/swagger-ui
# Or use auto-detection script
cat > start-swagger.sh << 'EOF'
#!/bin/bash
PORTS=(8081 8082 8083 9000)
for port in "${PORTS[@]}"; do
if ! netstat -tlnp 2>/dev/null | grep ":$port " > /dev/null; then
echo "π Starting Swagger UI on port $port"
docker run -d --name swagger-finsolvz -p $port:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $(pwd)/api:/app swaggerapi/swagger-ui
echo "β
Swagger UI: http://localhost:$port"
break
fi
done
EOF
chmod +x start-swagger.sh
./start-swagger.shOpen your browser to: http://localhost:8082 (or the port shown in terminal)
- Find
GET /endpoint - Click "Try it out"
- Click "Execute"
- Should return status "healthy"
- Find
POST /api/loginendpoint - Click "Try it out"
- Enter credentials:
{ "email": "[email protected]", "password": "admin123" } - Click "Execute"
- Copy the
access_tokenfrom response
- Click "Authorize" button (π) at top right
- Enter:
Bearer YOUR_ACCESS_TOKEN - Click "Authorize"
Now you can test:
GET /api/users- Get all usersGET /api/loginUser- Get current user infoGET /api/company- Get companiesGET /api/reportTypes- Get report typesPOST /api/register- Create new user (SUPER_ADMIN only)
{
"name": "John Doe",
"email": "[email protected]",
"password": "securePassword123!",
"role": "CLIENT"
}{
"name": "Acme Corporation",
"profilePicture": "https://example.com/logo.png",
"user": ["USER_ID_HERE"]
}{
"name": "Monthly Financial Report"
}# Start backend
go run cmd/server/main.go
# Create admin user
go run create_admin.go
# Start Swagger UI
docker run -d --name swagger-finsolvz -p 8082:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $(pwd)/api:/app swaggerapi/swagger-ui
# View Swagger logs
docker logs swagger-finsolvz
# Stop Swagger UI
docker stop swagger-finsolvz
# Remove Swagger container
docker rm swagger-finsolvzCreate a development helper script:
cat > dev.sh << 'EOF'
#!/bin/bash
echo "π Finsolvz Development Helper"
echo "==============================="
case "$1" in
"start")
echo "Starting all services..."
# Start MongoDB if using Docker
docker start mongo-finsolvz 2>/dev/null || echo "MongoDB: start manually or use Atlas"
# Start Swagger UI
docker stop swagger-finsolvz 2>/dev/null || true
docker rm swagger-finsolvz 2>/dev/null || true
docker run -d --name swagger-finsolvz -p 8082:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $(pwd)/api:/app swaggerapi/swagger-ui
echo "β
Swagger UI: http://localhost:8082"
echo "π§ Now run: go run cmd/server/main.go"
;;
"stop")
echo "Stopping services..."
docker stop swagger-finsolvz mongo-finsolvz 2>/dev/null || true
echo "β
Services stopped"
;;
"status")
echo "Service Status:"
echo "==============="
# Check backend
if curl -s http://localhost:8787 > /dev/null 2>&1; then
echo "β
Backend API: http://localhost:8787"
else
echo "β Backend API: Not running"
fi
# Check Swagger
if curl -s http://localhost:8082 > /dev/null 2>&1; then
echo "β
Swagger UI: http://localhost:8082"
else
echo "β Swagger UI: Not running"
fi
# Check MongoDB
if docker ps | grep mongo-finsolvz > /dev/null; then
echo "β
MongoDB: Running in Docker"
else
echo "βΉοΈ MongoDB: Check manual installation or Atlas"
fi
;;
"test")
echo "Testing API..."
# Test health
echo "1. Health Check:"
curl -s http://localhost:8787 | grep -o '"message":"[^"]*"' || echo "β Backend not responding"
# Test login
echo -e "\n2. Login Test:"
response=$(curl -s -X POST http://localhost:8787/api/login \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"admin123"}')
if echo "$response" | grep -q "access_token"; then
echo "β
Login successful"
else
echo "β Login failed: $response"
fi
;;
*)
echo "Usage: ./dev.sh {start|stop|status|test}"
echo ""
echo "Commands:"
echo " start - Start Swagger UI and MongoDB"
echo " stop - Stop all services"
echo " status - Check service status"
echo " test - Test API endpoints"
echo ""
echo "Manual commands:"
echo " Backend: go run cmd/server/main.go"
echo " Admin: go run create_admin.go"
;;
esac
EOF
chmod +x dev.shUsage:
./dev.sh start # Start services
./dev.sh status # Check status
./dev.sh test # Test API
./dev.sh stop # Stop servicesdocker build -t finsolvz-backend .version: '3.8'
services:
finsolvz-backend:
build: .
ports:
- "8787:8787"
environment:
- MONGO_URI=mongodb://mongo:27017/Finsolvz
- JWT_SECRET=your-production-secret
depends_on:
- mongo
mongo:
image: mongo:7.0
ports:
- "27017:27017"
volumes:
- mongo_data:/data/db
swagger-ui:
image: swaggerapi/swagger-ui
ports:
- "8082:8080"
environment:
- SWAGGER_JSON=/app/openapi.yaml
volumes:
- ./api:/app
volumes:
mongo_data:# Build and deploy to Cloud Run
gcloud builds submit --tag gcr.io/PROJECT_ID/finsolvz-backend
gcloud run deploy finsolvz-backend \
--image gcr.io/PROJECT_ID/finsolvz-backend \
--platform managed \
--region asia-southeast2 \
--allow-unauthenticated# Find what's using the port
sudo netstat -tlnp | grep :8082
# Kill the process
sudo fuser -k 8082/tcp
# Or use different port
docker run -p 8083:8080 ...# Add user to docker group
sudo usermod -aG docker $USER
# Restart WSL
exit
wsl# Check current directory
pwd
# Use absolute path
docker run -v "/full/path/to/project/api:/app" ...
# Or copy method
docker cp api/openapi.yaml container_name:/usr/share/nginx/html/# Check MongoDB status
sudo systemctl status mongodb
# Check connection string in .env
echo $MONGO_URI
# Test connection
mongo $MONGO_URIAll requests and errors are logged with structured format. Check logs in development:
# Backend logs
go run cmd/server/main.go
# Docker container logs
docker logs swagger-finsolvz
docker logs mongo-finsolvz- Documentation: Swagger UI at http://localhost:8082
- API Base URL: http://localhost:8787
- Default Admin: [email protected] / admin123
-
Setup Environment:
# WSL with Go, Docker, MongoDB git clone <repo> cp .env.example .env go mod tidy
-
Start Services:
./dev.sh start # Start Swagger UI go run cmd/server/main.go # Start backend
-
Create Admin:
go run create_admin.go
-
Test API:
- Open http://localhost:8082
- Login to get token
- Authorize and test endpoints
-
Development Loop:
- Modify code
- Restart backend
- Test in Swagger UI
- Update documentation in
api/openapi.yaml
Built with β€οΈ for financial solutions management