Eco Van API

Backend API for the Eco Van waste management system ("Спецэкогруз").

Features

• Clients Management - Company and object management
• Equipment Management - Waste bins and containers
• Transport Management - Vehicle fleet management
• Drivers Management - Personnel management
• Orders Management - Waste collection request processing
• Photo Management - File upload and storage

Tech Stack

• Language: Go 1.21+
• Database: PostgreSQL
• ORM: SQLC (SQL Compiler)
• Migrations: golang-migrate
• Linting: golangci-lint
• Testing: Go testing package
• Mocking: Mockery

Prerequisites

• Go 1.21 or higher
• PostgreSQL 12 or higher
• Make (for build automation)

Local Development

1. Clone and Setup

git clone <repository-url>
cd eco-van-api

2. Environment Setup (Recommended)

# Setup environment files (.env and .env.test)
make env-setup

# Or complete development setup (tools + environment)
make dev-setup

This creates:

• .env - Local development configuration
• .env.test - Integration test configuration

3. Install Development Tools

make tools

This will install:

• sqlc - SQL compiler for type-safe database queries
• migrate - Database migration tool
• golangci-lint - Linting tool
• mockery - Mock generation tool

4. Database Setup

Option A: Docker (Recommended)

# Start development database with automatic migrations
make db

# Start test database with automatic migrations
make test-db

Option B: Manual PostgreSQL Setup

# Create database
make db-create

# Run migrations
make migrate-up

Note: Update the database connection string in the Makefile if your PostgreSQL setup differs.

5. Install Dependencies

make deps

6. Generate Code

make gen

This generates:

• SQLC code from SQL queries
• Mock interfaces for testing

7. Run the Application

# Development mode (automatically starts DB + loads .env)
make run

# Or build and run
make build
./bin/eco-van-api

Development Commands

Code Quality

# Run linter
make lint

# Format code
make fmt

# Vet code
make vet

# Run tests
make test

# Run security checks
make security

# Run benchmarks
make bench

Database Operations

Docker-based (Recommended)

# Development database
make db                    # Start development DB with migrations
make db-stop              # Stop development DB container
make db-reset-docker      # Reset development DB container

# Test database
make test-db              # Start test DB with migrations
make test-db-stop         # Stop test DB container
make test-db-reset        # Reset test DB container

Manual PostgreSQL

# Run migrations up
make migrate-up

# Run migrations down
make migrate-down

# Reset database (drop, create, migrate)
make db-reset

Build Operations

# Build application
make build

# Clean build artifacts
make clean

# Docker operations
make docker-build
make docker-run

Enhanced Makefile Commands

Quick Start Commands

# Complete development setup (tools + environment + code generation)
make dev-setup

# Start application with automatic database setup
make run

# Run integration tests with automatic test database setup
make test-integration

Database Management

# Development database (port 5432)
make db              # Start with migrations
make db-stop         # Stop container
make db-reset-docker # Reset container

# Test database (port 5433)
make test-db         # Start with migrations
make test-db-stop    # Stop container
make test-db-reset   # Reset container

Environment Management

# Setup environment files
make env-setup       # Create .env and .env.test

# View all available commands
make help

Integration Testing

# Run integration tests (automatically manages test database)
make test-integration      # Normal mode
make test-integration-race # With race detection

Features:

• ✅ Automatic database container management
• ✅ Automatic migration application
• ✅ Environment variable loading from files
• ✅ Container reinitialization for fresh test data
• ✅ Port separation (dev: 5432, test: 5433)
• ✅ Transaction-per-test isolation

Pre-commit Checks

# Run all pre-commit checks
make pre-commit

Project Structure

eco-van-api/
├── cmd/
│   └── api/           # Application entry point
├── internal/           # Private application code
│   ├── api/           # HTTP handlers
│   ├── config/        # Configuration
│   ├── database/      # Database layer
│   ├── models/        # Data models
│   ├── services/      # Business logic
│   └── mocks/         # Generated mocks
├── db/                # Database related files
│   ├── migrations/    # Database migrations
│   ├── queries/       # SQL queries for SQLC
│   └── sqlc.yaml      # SQLC configuration
├── pkg/               # Public packages
├── scripts/           # Build and deployment scripts
├── Makefile           # Build automation
├── tools.go           # Tool dependencies
└── README.md          # This file

Configuration

The application uses environment variables for configuration. Two environment files are supported:

.env - Local Development

# Server Configuration
HTTP_ADDR=:8080
HTTP_READ_TIMEOUT=15s
HTTP_WRITE_TIMEOUT=15s
HTTP_IDLE_TIMEOUT=60s
HTTP_MAX_BODY=10485760
CORS_ORIGINS=*

# Database Configuration
DB_DSN=postgres://app:app@localhost:5432/eco_van_db?sslmode=disable
DB_MAX_CONNS=10
DB_MIN_CONNS=2
DB_MAX_CONN_LIFETIME=30m
DB_MAX_CONN_IDLE=10m

# Authentication
JWT_SECRET=your-secret-key-change-in-production
ACCESS_TTL=15m
REFRESH_TTL=720h

# Admin User (created automatically on first run)
ADMIN_PASSWORD=your-admin-password-change-in-production

# Telemetry
LOG_LEVEL=info
OTLP_ENDPOINT=
ENABLE_METRICS=true
ENABLE_TRACING=false

# Photos
PHOTOS_DIR=/photos

.env.test - Integration Tests

# Test Database Configuration
DB_DSN=postgres://app:app@localhost:5433/waste_test?sslmode=disable
DB_MAX_CONNS=5
DB_MIN_CONNS=1
DB_MAX_CONN_LIFETIME=5m
DB_MAX_CONN_IDLE=1m

# Test Authentication
JWT_SECRET=test-secret-key

# Test Admin User
ADMIN_PASSWORD=test-admin-password

# Test Telemetry
LOG_LEVEL=warn
ENABLE_METRICS=false
ENABLE_TRACING=false

Automatic Setup

# Create both environment files
make env-setup

# Or include in complete setup
make dev-setup

Authentication & Admin User

Admin User Setup

The application automatically creates an admin user on first startup:

• Email: admin@example.com
• Role: ADMIN
• Password: Set via ADMIN_PASSWORD environment variable
• Default Password: admin123456 (if ADMIN_PASSWORD not set)

Environment Variables

# Required for admin user creation
ADMIN_PASSWORD=your-secure-admin-password

# JWT configuration
JWT_SECRET=your-jwt-secret-key
ACCESS_TTL=15m      # Access token lifetime
REFRESH_TTL=720h    # Refresh token lifetime (30 days)

First Login

After starting the application for the first time:

1. Admin user is automatically created with the configured password
2. Login endpoint: POST /api/v1/auth/login
3. Request body:

   {
     "email": "admin@example.com",
     "password": "your-admin-password"
   }

4. Response: Access and refresh tokens

   {
     "accessToken": "eyJ...",
     "refreshToken": "eyJ...",
     "expiresIn": 900
   }

Token Usage

• Access Token: Include in Authorization: Bearer <token> header
• Token Expiry: 15 minutes (configured via ACCESS_TTL)
• Refresh Token: Use to get new access tokens via POST /api/v1/auth/refresh
• Refresh Expiry: 30 days (configured via REFRESH_TTL)

Protected Endpoints

All user management endpoints require authentication:

# List users (requires valid access token)
GET /api/v1/users
Authorization: Bearer <access-token>

# Create user (ADMIN role required)
POST /api/v1/users
Authorization: Bearer <access-token>

# Get user details
GET /api/v1/users/{id}
Authorization: Bearer <access-token>

# Delete user (ADMIN role required)
DELETE /api/v1/users/{id}
Authorization: Bearer <access-token>

Role-Based Access Control

• ADMIN: Full access to all endpoints
• DISPATCHER: Can view users, limited management
• DRIVER: Basic user information access
• VIEWER: Read-only access to user data

Testing

Unit Tests

# Run all tests
make test

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific test
go test ./internal/services/...

# Run tests with race detection
go test -race ./...

Integration Tests

# Run integration tests (automatically starts test DB + loads .env.test)
make test-integration

# Run integration tests with race detection
make test-integration-race

# View test coverage
go tool cover -html=coverage.out

Note: Integration tests use ephemeral PostgreSQL containers and automatically:

• Start a fresh test database
• Apply all migrations
• Run tests in isolated transactions
• Clean up containers after completion

Linting

# Run linter
make lint

# Auto-fix some issues
golangci-lint run --fix ./...

Code Generation

# Generate SQLC code
sqlc generate

# Generate mocks
mockery --all --output=internal/mocks --outpkg=mocks

Database Migrations

# Create new migration
migrate create -ext sql -dir db/migrations -seq migration_name

# Run migrations up
make migrate-up

# Run migrations down
make migrate-down

# Check migration status
migrate -path db/migrations -database "postgres://localhost:5432/eco_van_db?sslmode=disable" version

Complete Development Workflow

First Time Setup

# 1. Clone and navigate
git clone <repository-url>
cd eco-van-api

# 2. Complete setup (tools + environment + code generation)
make dev-setup

# 3. Start development database
make db

# 4. Start application
make run

Note: The make env-setup command creates default environment files. You may want to customize:

• ADMIN_PASSWORD: Set a secure password for the admin user
• JWT_SECRET: Use a strong, unique secret key
• DB_DSN: Adjust database connection if needed

Daily Development

# Start application (automatically starts DB if needed)
make run

# Run tests
make test

# Run integration tests (automatically starts test DB)
make test-integration

# Stop development database when done
make db-stop

Integration Testing

# Run integration tests (fresh test database each time)
make test-integration

# Run with race detection
make test-integration-race

# Clean up test database
make test-db-stop

Troubleshooting

Common Issues

1. Tools not found: Run make tools to install development tools
2. Database connection failed:
   • For Docker: Run make db or make test-db
   • For manual: Check PostgreSQL is running and credentials are correct
3. Migrations fail:
   • For Docker: Containers automatically apply migrations
   • For manual: Ensure database exists and user has proper permissions
4. Code generation fails: Check SQLC configuration and SQL syntax
5. Port conflicts:
   • Development DB uses port 5432
   • Test DB uses port 5433
   • Use make db-stop and make test-db-stop to free ports
6. Authentication issues:
   • Check ADMIN_PASSWORD is set in .env
   • Verify JWT_SECRET is configured
   • Ensure admin user exists (check application startup logs)
   • Check database migrations have been applied
7. Protected endpoint access:
   • Include Authorization: Bearer <token> header
   • Verify token hasn't expired (15 minutes for access tokens)
   • Check user has required role for the endpoint

Getting Help

• Check the Makefile targets: make help
• Review error messages and logs
• Ensure all prerequisites are installed
• Check database connection and permissions
• View available commands: make help
• Check environment files: .env and .env.test
• Verify Docker containers: docker ps

Environment File Structure

The project uses two environment files for different purposes:

• .env - Local development configuration

  • Loaded automatically by make run
  • Contains production-like settings
  • Database: eco_van_db on port 5432

• .env.test - Integration test configuration

  • Loaded automatically by make test-integration
  • Contains test-specific settings
  • Database: waste_test on port 5433

Note: Both files are created automatically by make env-setup and contain all necessary configuration variables.

Important Environment Variables

• ADMIN_PASSWORD: Password for the automatically created admin user
• JWT_SECRET: Secret key for signing JWT tokens (change in production)
• DB_DSN: Database connection string
• ACCESS_TTL: Access token lifetime (default: 15 minutes)
• REFRESH_TTL: Refresh token lifetime (default: 30 days)

New Features & Enhancements

🚀 Enhanced Makefile Commands

• Automatic Database Management: make db and make test-db now include migrations
• Environment Integration: make run automatically loads .env and starts database
• Test Automation: make test-integration automatically manages test database
• Container Reinitialization: Fresh test data for each integration test run

🐳 Docker-based Development

• Development Database: PostgreSQL on port 5432 with automatic migrations
• Test Database: PostgreSQL on port 5433 with automatic migrations
• Container Lifecycle: Easy start/stop/reset commands
• Port Separation: No conflicts between development and testing

🔧 Environment Management

• Automatic Setup: make env-setup creates configuration files
• File-based Config: .env for development, .env.test for testing
• Variable Loading: Automatic environment variable loading in commands

🧪 Integration Testing

• Ephemeral Databases: Fresh PostgreSQL containers for each test run
• Transaction Isolation: Each test runs in its own transaction
• Automatic Cleanup: Containers removed after test completion
• Race Detection: Support for concurrent testing

🔐 Authentication System

• JWT Tokens: Access (15m) and refresh (30d) token support
• Password Security: Argon2id hashing with configurable parameters
• Role-Based Access: ADMIN, DISPATCHER, DRIVER, VIEWER roles
• Admin Auto-Seeding: Automatic admin user creation on startup
• Protected Endpoints: Middleware-based route protection
• Problem JSON: RFC 7807 compliant error responses

Contributing

1. Follow Go best practices and conventions
2. Write tests for new functionality
3. Ensure linting passes: make lint
4. Run tests before committing: make test
5. Run integration tests: make test-integration
6. Use conventional commit messages
7. Test with both unit and integration tests

License

[Add your license information here]