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

```bash
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)

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

## 2. (Optional) Start Neo4j

```bash
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/`:

```bash
# 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

```bash
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

```bash
curl http://localhost:8080/health
```

Response:

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

### Create Organization

```bash
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

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

### Create Site

```bash
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)

```bash
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`:

```bash
NEO4J_ENABLED=true
```

3. Restart server:

```bash
./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:

```bash
curl http://localhost:8080/health
```

Response:

```json
{
  "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:

```bash
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](./SERVER_MIGRATION_SUMMARY.md) - Detailed migration docs
- [GRAPH_DATABASE_INTEGRATION.md](./GRAPH_DATABASE_INTEGRATION.md) - Neo4j integration guide
- [concept/](../concept/) - System design and architecture docs
- [dev_guides/](../dev_guides/) - Framework-specific guides