# Development Environment

## Prerequisites

- **Docker Engine 24+** & Docker Compose v2
- **Node.js 22 LTS**
- **pnpm 10.27+** — install via `corepack enable && corepack prepare pnpm@latest --activate`

## Quick Start

```bash
# 1. Copy environment variables
cp .env.example .env

# 2. Start all infrastructure services
docker compose up -d

# 3. Verify all services are healthy
docker compose ps

# 4. Install dependencies
pnpm install

# 5. Generate Prisma client
pnpm db:generate

# 6. Run database migrations
pnpm db:migrate:dev

# 7. Seed the database (optional)
pnpm db:seed

# 8. Start API and Web in dev mode
pnpm dev
```

API runs at `http://localhost:3001/api/v1`, Web at `http://localhost:3000`.

> **Swagger UI**: `http://localhost:3001/api/v1/docs` — interactive API documentation.

## Infrastructure Services

| Service | Port(s) | Description | Dashboard/UI |
|---------|---------|-------------|--------------|
| PostgreSQL + PostGIS | 5432 | Database with spatial queries | — |
| Redis | 6379 | Cache, sessions, queue | — |
| Typesense | 8108 | Full-text search engine | `http://localhost:8108/health` |
| MinIO | 9000 / 9001 | S3-compatible object storage | `http://localhost:9001` (console) |
| AI Services | 8000 | FastAPI — AVM + moderation | `http://localhost:8000/health` |
| Prometheus | 9090 | Metrics collection | `http://localhost:9090` |
| Grafana | 3002 | Dashboards & monitoring | `http://localhost:3002` |

## Common Commands

### Docker Compose

```bash
# Start services
docker compose up -d

# View logs (all or specific service)
docker compose logs -f
docker compose logs -f postgres

# Stop services (data preserved in volumes)
docker compose down

# Stop and remove all data
docker compose down -v

# Restart a single service
docker compose restart redis

# Check service health
docker compose ps
```

### Development

```bash
pnpm dev              # Start all apps in watch mode
pnpm build            # Build all packages
pnpm lint             # ESLint across monorepo
pnpm typecheck        # TypeScript type checking
pnpm format           # Prettier formatting
pnpm test             # Run unit/integration tests
```

### Database

```bash
pnpm db:generate      # Regenerate Prisma client
pnpm db:migrate:dev   # Create and apply migrations
pnpm db:seed          # Seed database
pnpm db:studio        # Open Prisma Studio (visual editor)
pnpm db:reset         # Reset database (destructive)
```

### E2E Testing

```bash
pnpm test:e2e         # Run all E2E tests
pnpm test:e2e:api     # API tests only
pnpm test:e2e:web     # Web UI tests only
pnpm test:e2e:report  # Open HTML test report
```

## Connecting to Services

### PostgreSQL

```bash
# Via psql
psql postgresql://goodgo:goodgo_secret@localhost:5432/goodgo

# Verify PostGIS
psql postgresql://goodgo:goodgo_secret@localhost:5432/goodgo -c "SELECT PostGIS_Version();"
```

### Redis

```bash
redis-cli -p 6379 ping
```

### Typesense

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

### MinIO

- **API**: `http://localhost:9000`
- **Console**: `http://localhost:9001` (login with `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` from your `.env`)

### AI Services

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

### Grafana

- **URL**: `http://localhost:3002`
- **Login**: `admin` / `admin` (default, configurable via `.env`)

## Troubleshooting

- **Port conflict** — Change ports in `.env` (e.g., `DB_PORT=5433`)
- **Permission issues** — Run `docker compose down -v` and restart
- **PostGIS not available** — Ensure using `postgis/postgis:16-3.4` image
- **Prisma client out of date** — Run `pnpm db:generate` after pulling schema changes
- **AI service not starting** — Check `docker compose logs ai-services` for Python dependency errors
- **Typesense unhealthy** — Verify `TYPESENSE_API_KEY` matches in `.env` and Docker config