turash/bugulma/backend/QUICKSTART.md

Quick Start Guide

Prerequisites

• Go 1.21+
• PostgreSQL 15+ with PostGIS extension
• (Optional) Neo4j 5.15+ for graph features

1. Start PostgreSQL

Using Docker

docker run -d \
  --name bugulma-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=bugulma_dev \
  -p 5432:5432 \
  postgis/postgis:15-3.4

Using Homebrew (macOS)

brew install postgresql@15 postgis
brew services start postgresql@15
createdb bugulma_dev

2. (Optional) Start Neo4j

docker run -d \
  --name bugulma-neo4j \
  -e NEO4J_AUTH=neo4j/password123 \
  -p 7474:7474 \
  -p 7687:7687 \
  neo4j:5.15

Access Neo4j Browser at: http://localhost:7474

3. Configure Environment

Create .env file in bugulma/backend/:

# PostgreSQL (Required)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=bugulma_dev
POSTGRES_SSLMODE=disable

# Neo4j (Optional)
NEO4J_ENABLED=false  # Set to "true" to enable graph features
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password123
NEO4J_DATABASE=neo4j

# Server
SERVER_PORT=8080
JWT_SECRET=your-secret-key-change-in-production
ENVIRONMENT=development

4. Build and Run

cd bugulma/backend

# Install dependencies
go mod download

# Build unified CLI
go build -o bin/bugulma-cli ./cmd/cli

# Run migrations
./bin/bugulma-cli migrate up

# Start server
./bin/bugulma-cli server

Expected output:

Successfully connected to PostgreSQL database
Neo4j integration disabled (set NEO4J_ENABLED=true to enable)
[GIN-debug] Listening and serving HTTP on :8080

5. Test API

Health Check

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "database": "connected"
}

Create Organization

curl -X POST http://localhost:8080/api/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Berlin Recycling GmbH",
    "sector": "waste_management",
    "subtype": "recycling_facility",
    "description": "Industrial waste recycling",
    "address": "Alexanderplatz 1, Berlin",
    "latitude": 52.5200,
    "longitude": 13.4050,
    "industrial_sector": "circular_economy"
  }'

Get Organizations

curl http://localhost:8080/api/organizations

Create Site

curl -X POST http://localhost:8080/api/sites \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Processing Plant",
    "address": "Industriestraße 10, Berlin",
    "latitude": 52.5100,
    "longitude": 13.3900,
    "site_type": "industrial_site",
    "floor_area_m2": 5000,
    "owner_business_id": "<organization_id>"
  }'

Find Matches (Graph-Based)

curl -X POST http://localhost:8080/api/matching/find-matches \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "heat",
    "max_distance_km": 10,
    "min_compatibility": 0.6
  }'

6. Enable Neo4j Graph Features

1. Start Neo4j (see step 2)

2. Update .env:

NEO4J_ENABLED=true

3. Restart server:

./bin/server

Expected output:

Successfully connected to PostgreSQL database
Neo4j integration enabled, initializing...
Neo4j schema initialized successfully
Neo4j graph database integration ready
[GIN-debug] Listening and serving HTTP on :8080

4. Verify graph DB in health check:

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "database": "connected",
  "graph_db": "connected"
}

Common Issues

PostgreSQL Connection Failed

Failed to connect to PostgreSQL: dial tcp [::1]:5432: connect: connection refused

Solution: Ensure PostgreSQL is running and POSTGRES_HOST is correct

Neo4j Connection Failed

Warning: Failed to connect to Neo4j: connection refused
Continuing without graph database integration

Solution:

• Check Neo4j is running: docker ps | grep neo4j
• Verify NEO4J_URI is correct (bolt://localhost:7687)
• Check credentials match Neo4j settings

Port Already in Use

bind: address already in use

Solution: Change SERVER_PORT in .env or kill process using port 8080:

lsof -ti:8080 | xargs kill -9

API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/api/organizations	List organizations
POST	/api/organizations	Create organization
GET	/api/organizations/:id	Get organization by ID
PUT	/api/organizations/:id	Update organization
GET	/api/sites	List sites
POST	/api/sites	Create site
GET	/api/sites/nearby?lat=X&lng=Y&radius=Z	Find nearby sites
GET	/api/resources	List resource flows
POST	/api/resources	Create resource flow
POST	/api/matching/find-matches	Find matching resources
GET	/api/stats/summary	Get system statistics

Next Steps

1. Add Authentication: Implement JWT-based auth (currently disabled)
2. Database Migrations: Create proper SQL migration scripts
3. Bulk Import: Add CSV/JSON import for initial data
4. Frontend: Connect React/Vue frontend to API
5. Documentation: Generate OpenAPI/Swagger docs

Resources

• SERVER_MIGRATION_SUMMARY.md - Detailed migration docs
• GRAPH_DATABASE_INTEGRATION.md - Neo4j integration guide
• concept/ - System design and architecture docs
• dev_guides/ - Framework-specific guides