# Quick Reference Guide

## 🚀 Starting Services

### Local Development (No Auth Required)

```bash
# Start infrastructure
make deploy-infra

# Run service locally without authentication
DISABLE_AUTH=true make dev-service SERVICE=svc_ingestion

# Test it
curl http://localhost:8000/healthz
```

### Docker Compose (Full Stack)

```bash
# Start all services
cd infra/compose
docker-compose -f docker-compose.local.yml up -d

# Check status
docker-compose -f docker-compose.local.yml ps

# View logs
docker-compose -f docker-compose.local.yml logs -f svc-ingestion

# Stop all services
docker-compose -f docker-compose.local.yml down
```

## 🔍 Checking Status

### Service Health

```bash
# Check all services
cd infra/compose
docker-compose -f docker-compose.local.yml ps

# Count healthy services
docker-compose -f docker-compose.local.yml ps | grep -c "healthy"

# Check specific service
docker-compose -f docker-compose.local.yml ps svc-ingestion
```

### Logs

```bash
# View service logs
cd infra/compose
docker-compose -f docker-compose.local.yml logs -f SERVICE_NAME

# View last 50 lines
docker-compose -f docker-compose.local.yml logs --tail=50 SERVICE_NAME

# View logs since 5 minutes ago
docker-compose -f docker-compose.local.yml logs --since 5m SERVICE_NAME

# Search logs for errors
docker-compose -f docker-compose.local.yml logs SERVICE_NAME | grep -i error
```

### Health Checks

```bash
# Check Traefik health check status
cd infra/compose
docker-compose -f docker-compose.local.yml logs traefik --since 5m | grep -i "health"

# Should show no errors (only certificate warnings are OK)
```

## 🧪 Testing

### Health Endpoints (No Auth Required)

```bash
# Health check
curl http://localhost:8000/healthz

# Readiness check
curl http://localhost:8000/readyz

# Liveness check
curl http://localhost:8000/livez

# API documentation
curl http://localhost:8000/docs
```

### Protected Endpoints (Auth Required)

```bash
# With authentication headers
curl -X POST http://localhost:8000/upload \
  -H "X-Authenticated-User: dev-user" \
  -H "X-Authenticated-Email: dev@example.com" \
  -H "Authorization: Bearer dev-token-12345" \
  -F "file=@document.pdf"
```

### Development Mode (No Auth Required)

```bash
# When running with DISABLE_AUTH=true
curl -X POST http://localhost:8000/upload \
  -F "file=@document.pdf"
```

## 🔧 Troubleshooting

### Service Won't Start

```bash
# Check logs for errors
cd infra/compose
docker-compose -f docker-compose.local.yml logs SERVICE_NAME --tail=100

# Restart service
docker-compose -f docker-compose.local.yml restart SERVICE_NAME

# Rebuild and restart
docker-compose -f docker-compose.local.yml up -d --build SERVICE_NAME
```

### Infrastructure Issues

```bash
# Check infrastructure services
cd infra/compose
docker-compose -f docker-compose.local.yml ps postgres redis minio neo4j

# Restart infrastructure
docker-compose -f docker-compose.local.yml restart postgres redis minio neo4j

# Check connectivity
docker-compose -f docker-compose.local.yml exec svc-ingestion ping -c 3 postgres
```

### Health Check Failures

```bash
# Check Traefik logs
cd infra/compose
docker-compose -f docker-compose.local.yml logs traefik --tail=100 | grep -i "health\|error"

# Test health endpoint directly
docker-compose -f docker-compose.local.yml exec SERVICE_NAME curl -f http://localhost:8000/healthz

# Restart Traefik
docker-compose -f docker-compose.local.yml restart traefik
```

### Authentication Issues

```bash
# For local development, disable auth
DISABLE_AUTH=true make dev-service SERVICE=svc_ingestion

# Check if auth is disabled in logs
# Should see: "Development mode: authentication disabled"

# For production mode, ensure headers are set
curl -v http://localhost:8000/upload \
  -H "X-Authenticated-User: dev-user" \
  -H "X-Authenticated-Email: dev@example.com" \
  -H "Authorization: Bearer dev-token-12345"
```

## 📊 Monitoring

### Service Metrics

```bash
# Prometheus
open http://localhost:9090

# Grafana
open http://localhost:3000

# Traefik Dashboard
open http://localhost:8080
```

### Database Access

```bash
# PostgreSQL
docker-compose -f infra/compose/docker-compose.local.yml exec postgres psql -U postgres

# Redis
docker-compose -f infra/compose/docker-compose.local.yml exec redis redis-cli

# Neo4j Browser
open http://localhost:7474
```

## 🛠️ Common Tasks

### Restart All Services

```bash
cd infra/compose
docker-compose -f docker-compose.local.yml restart
```

### Restart Single Service

```bash
cd infra/compose
docker-compose -f docker-compose.local.yml restart svc-ingestion
```

### View Service Configuration

```bash
cd infra/compose
docker-compose -f docker-compose.local.yml config | grep -A 20 "svc-ingestion:"
```

### Clean Up

```bash
# Stop all services
cd infra/compose
docker-compose -f docker-compose.local.yml down

# Stop and remove volumes (⚠️ deletes data)
docker-compose -f docker-compose.local.yml down -v

# Remove all containers and images
docker-compose -f docker-compose.local.yml down --rmi all
```

### Update Service

```bash
# Rebuild and restart
cd infra/compose
docker-compose -f docker-compose.local.yml up -d --build svc-ingestion

# View logs
docker-compose -f docker-compose.local.yml logs -f svc-ingestion
```

## 🔐 Environment Variables

### Development Mode

```bash
# Disable authentication
export DISABLE_AUTH=true

# Enable development mode
export DEV_MODE=true

# Run service
make dev-service SERVICE=svc_ingestion
```

### Production Mode

```bash
# Enable authentication (default)
unset DISABLE_AUTH
unset DEV_MODE

# Run service
make dev-service SERVICE=svc_ingestion
```

## 📝 Postman

### Quick Setup

1. **Create Environment**: "AI Tax Agent - Development"
2. **Add Variables**:
   - `base_url`: `http://localhost:8000`
   - `auth_user`: `dev-user`
   - `auth_email`: `dev@example.com`
   - `auth_token`: `Bearer dev-token-12345`

3. **For Development Mode**: No headers needed
4. **For Production Mode**: Add headers:
   - `X-Authenticated-User`: `{{auth_user}}`
   - `X-Authenticated-Email`: `{{auth_email}}`
   - `Authorization`: `{{auth_token}}`

See [POSTMAN_SETUP.md](POSTMAN_SETUP.md) for detailed instructions.

## 📚 Documentation

- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Complete development guide
- **[INFRASTRUCTURE_STATUS.md](INFRASTRUCTURE_STATUS.md)** - Infrastructure status report
- **[POSTMAN_SETUP.md](POSTMAN_SETUP.md)** - Postman setup guide
- **[FIXES_APPLIED.md](FIXES_APPLIED.md)** - Recent fixes and changes

## 🆘 Getting Help

### Check Service Status

```bash
# All services
cd infra/compose
docker-compose -f docker-compose.local.yml ps

# Specific service
docker-compose -f docker-compose.local.yml ps svc-ingestion
```

### Check Logs

```bash
# Recent logs
cd infra/compose
docker-compose -f docker-compose.local.yml logs --tail=100 svc-ingestion

# Follow logs
docker-compose -f docker-compose.local.yml logs -f svc-ingestion
```

### Check Health

```bash
# Health endpoint
curl http://localhost:8000/healthz

# Docker health check
cd infra/compose
docker-compose -f docker-compose.local.yml ps | grep svc-ingestion
```

### Common Issues

| Issue | Solution |
|-------|----------|
| 401 Unauthorized | Use `DISABLE_AUTH=true` or add auth headers |
| Connection refused | Check service is running: `docker-compose ps` |
| 500 Internal Error | Check logs: `docker-compose logs SERVICE_NAME` |
| Health check failing | Check Traefik logs: `docker-compose logs traefik` |
| Port already in use | Stop conflicting service or change port |

## 🎯 Quick Commands

```bash
# Start everything
make deploy-infra && DISABLE_AUTH=true make dev-service SERVICE=svc_ingestion

# Check status
curl http://localhost:8000/healthz

# View logs
cd infra/compose && docker-compose -f docker-compose.local.yml logs -f svc-ingestion

# Restart service
cd infra/compose && docker-compose -f docker-compose.local.yml restart svc-ingestion

# Stop everything
cd infra/compose && docker-compose -f docker-compose.local.yml down
```

## 🔄 Service Ports

| Service | Port | Access |
|---------|------|--------|
| svc-ingestion | 8000 | http://localhost:8000 |
| PostgreSQL | 5432 | localhost:5432 |
| Redis | 6379 | localhost:6379 |
| MinIO Console | 9093 | http://localhost:9093 |
| MinIO API | 9092 | http://localhost:9092 |
| Neo4j Browser | 7474 | http://localhost:7474 |
| Neo4j Bolt | 7687 | bolt://localhost:7687 |
| Qdrant | 6333 | http://localhost:6333 |
| NATS | 4222 | nats://localhost:4222 |
| Prometheus | 9090 | http://localhost:9090 |
| Grafana | 3000 | http://localhost:3000 |
| Traefik Dashboard | 8080 | http://localhost:8080 |
| Vault | 8200 | http://localhost:8200 |
| Unleash | 4242 | http://localhost:4242 |

## ✅ Health Check

Run this to verify everything is working:

```bash
#!/bin/bash
echo "🔍 Checking infrastructure..."
cd infra/compose

# Check services
HEALTHY=$(docker-compose -f docker-compose.local.yml ps | grep -c "healthy")
echo "✅ Healthy services: $HEALTHY"

# Check Traefik
ERRORS=$(docker-compose -f docker-compose.local.yml logs traefik --since 5m | grep -c "Health check failed")
if [ $ERRORS -eq 0 ]; then
  echo "✅ No health check errors"
else
  echo "❌ Found $ERRORS health check errors"
fi

# Test endpoint
if curl -s http://localhost:8000/healthz > /dev/null; then
  echo "✅ Service responding"
else
  echo "❌ Service not responding"
fi
```

Save this as `check-health.sh` and run with `bash check-health.sh`