ai-tax-agent/docs/QUICK_REFERENCE.md

Quick Reference Guide

🚀 Starting Services

Local Development (No Auth Required)

# 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)

# 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

# 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

# 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

# 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)

# 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)

# 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)

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

🔧 Troubleshooting

Service Won't Start

# 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

# 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

# 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

# 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

# Prometheus
open http://localhost:9090

# Grafana
open http://localhost:3000

# Traefik Dashboard
open http://localhost:8080

Database Access

# 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

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

Restart Single Service

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

View Service Configuration

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

Clean Up

# 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

# 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

# Disable authentication
export DISABLE_AUTH=true

# Enable development mode
export DEV_MODE=true

# Run service
make dev-service SERVICE=svc_ingestion

Production Mode

# 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 for detailed instructions.

📚 Documentation

• DEVELOPMENT.md - Complete development guide
• INFRASTRUCTURE_STATUS.md - Infrastructure status report
• POSTMAN_SETUP.md - Postman setup guide
• FIXES_APPLIED.md - Recent fixes and changes

🆘 Getting Help

Check Service Status

# 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

# 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

# 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

# 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:

#!/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