Initial commit

docs/QUICK_REFERENCE.md

@@ -0,0 +1,416 @@
+# 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`
+