diff --git a/DEVELOPER_QUICK_REFERENCE.md b/DEVELOPER_QUICK_REFERENCE.md new file mode 100644 index 0000000..1eb9a17 --- /dev/null +++ b/DEVELOPER_QUICK_REFERENCE.md @@ -0,0 +1,301 @@ +# 🚀 Developer Quick Reference Guide + +## 📋 Essential Information for Developers + +This guide provides all the critical information needed to work with the CIM Document Processor project, including production versions, deployment procedures, and troubleshooting. + +## 🔑 Authentication & Access + +### **Gitea Repository** +- **URL**: `https://gitea.pressmess.duckdns.org/admin/cim_summary.git` +- **Username**: `admin` +- **Password**: `MyN3wP@ssword!` + +### **Firebase Projects** +- **Production**: `cim-summarizer` +- **Testing**: `cim-summarizer-testing` + +### **Environment Setup** +```bash +# Clone repository +git clone https://gitea.pressmess.duckdns.org/admin/cim_summary.git +cd cim_summary + +# Set up authentication +git config --global credential.helper store +git config --global user.name "admin" +git config --global user.email "admin@gitea.pressmess.duckdns.org" +``` + +## 🏷️ Production Version Tags + +### **Critical Version Tags** +```bash +# Production backup versions +PRODUCTION-BACKUP-v1.0 # e0a37bf - Stable deployment before major updates +PRODUCTION-BACKUP-v1.1 # b319ae0 - Clean state before inline editing features +CURRENT-PRODUCTION # 57770fd - Currently deployed on master +``` + +### **Current Branches** +```bash +main-cloud-native # Main development branch +preview-capabilities-phase1-2 # Current preview branch with Claude 3.7 +backup-live-version-e0a37bf # Production backup branch +backup-live-version-e0a37bf-clean # Clean production backup +``` + +## 🔄 Version Management Commands + +### **Quick Version Comparison** +```bash +# Use the version comparison script +./scripts/version-compare.sh versions # Show all versions +./scripts/version-compare.sh compare v1 v2 # Compare versions +./scripts/version-compare.sh rollback PRODUCTION-BACKUP-v1.0 # Create rollback +./scripts/version-compare.sh details CURRENT-PRODUCTION # Show version details +``` + +### **Direct Git Commands** +```bash +# Compare current preview with production +git diff CURRENT-PRODUCTION..preview-capabilities-phase1-2 + +# Compare with backup versions +git diff PRODUCTION-BACKUP-v1.0..preview-capabilities-phase1-2 +git diff PRODUCTION-BACKUP-v1.1..preview-capabilities-phase1-2 + +# Checkout specific versions +git checkout PRODUCTION-BACKUP-v1.0 +git checkout CURRENT-PRODUCTION +git checkout preview-capabilities-phase1-2 +``` + +## 🚀 Deployment Procedures + +### **Testing Environment Deployment** +```bash +# Deploy to testing +cd backend +firebase use cim-summarizer-testing +firebase deploy --only functions +``` + +### **Production Deployment** +```bash +# Deploy to production +cd backend +firebase use cim-summarizer +firebase deploy --only functions +``` + +### **Emergency Rollback** +```bash +# Create rollback branch +git checkout PRODUCTION-BACKUP-v1.0 +git checkout -b emergency-rollback-$(date +%Y%m%d) + +# Deploy rollback +firebase use cim-summarizer +firebase deploy --only functions +``` + +## 🔧 Key Configuration Files + +### **Environment Configuration** +- `backend/src/config/env.ts` - Main environment configuration +- `backend/.env.production` - Production environment variables +- `backend/.env.firebase` - Firebase environment variables + +### **LLM Configuration** +- **Primary Model**: `claude-3-7-sonnet-latest` +- **API Version**: `2024-01-01` +- **Provider**: Anthropic +- **Fallback**: Claude 3.5 models + +### **Firebase Configuration** +- `backend/firebase.json` - Firebase Functions configuration +- `backend/.firebaserc` - Firebase project settings + +## 🐛 Troubleshooting Guide + +### **Common Issues & Solutions** + +#### **1. Authentication Errors (401)** +```bash +# Check authentication +firebase login +firebase projects:list + +# Verify credentials +git config --global user.name +git config --global user.email +``` + +#### **2. LLM Processing Failures** +```bash +# Check LLM configuration +grep -r "claude-3-7" backend/src/config/ +grep -r "anthropic-version" backend/src/services/ + +# Verify API keys +echo $ANTHROPIC_API_KEY +echo $OPENAI_API_KEY +``` + +#### **3. Document Processing Issues** +```bash +# Check document status +node backend/check-document-status.js + +# Debug processing +node backend/debug-llm-processing.js +node backend/debug-processing.js +``` + +#### **4. Database Connection Issues** +```bash +# Test Supabase connection +node backend/test-supabase-connection.js + +# Check database tables +node backend/check-columns.js +node backend/create-missing-tables.js +``` + +### **Debug Scripts** +```bash +# Available debug scripts +backend/debug-processing.js # Debug document processing +backend/debug-llm-processing.js # Debug LLM calls +backend/test-complete-pipeline.js # Test full pipeline +backend/test-document-ai-simple.js # Test Document AI +backend/test-llm-simple.js # Test LLM service +``` + +## 📊 Monitoring & Logs + +### **Firebase Logs** +```bash +# View Firebase Functions logs +firebase functions:log --only cim-processor-backend + +# Real-time logs +firebase functions:log --only cim-processor-backend --follow +``` + +### **Application Health** +```bash +# Health check endpoints +curl https://cim-summarizer.web.app/health +curl https://cim-summarizer-testing.web.app/health +``` + +## 🔐 Security & API Keys + +### **Required Environment Variables** +```bash +# Anthropic (Primary LLM) +ANTHROPIC_API_KEY=your_anthropic_key + +# OpenAI (Fallback LLM) +OPENAI_API_KEY=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 + +# Supabase +SUPABASE_URL=your_supabase_url +SUPABASE_ANON_KEY=your_supabase_key + +# Firebase +FB_PROJECT_ID=cim-summarizer +``` + +### **Service Account Keys** +- `backend/serviceAccountKey.json` - Production Google Cloud service account +- `backend/serviceAccountKey-testing.json` - Testing Google Cloud service account + +## 📁 Project Structure + +### **Key Directories** +``` +backend/ +├── src/ +│ ├── config/ # Configuration files +│ ├── controllers/ # API controllers +│ ├── services/ # Business logic services +│ ├── models/ # Database models +│ └── routes/ # API routes +├── scripts/ # Utility scripts +└── dist/ # Compiled code + +frontend/ +├── src/ +│ ├── components/ # React components +│ ├── services/ # API services +│ └── config/ # Frontend configuration +└── dist/ # Built frontend +``` + +## 🚨 Emergency Procedures + +### **Critical Issues** +1. **Production Down**: Rollback to `PRODUCTION-BACKUP-v1.0` +2. **LLM Failures**: Check API keys and model availability +3. **Database Issues**: Verify Supabase connection and tables +4. **Authentication Problems**: Check Firebase configuration + +### **Emergency Contacts** +- **Repository**: Gitea admin access +- **Firebase**: Google Cloud Console +- **Supabase**: Supabase Dashboard +- **LLM Services**: Anthropic/OpenAI dashboards + +## 📚 Additional Resources + +### **Documentation Files** +- `PRODUCTION_VERSION_REFERENCE.md` - Detailed version management +- `MIGRATION_QUICK_REFERENCE.md` - Migration procedures +- `PRODUCTION_MIGRATION_GUIDE.md` - Production deployment guide +- `PHASE9_SUMMARY.md` - Latest implementation details + +### **Useful Commands** +```bash +# Quick status check +git status +git log --oneline -5 + +# Environment check +node -e "console.log(process.env.NODE_ENV)" +firebase projects:list + +# Health check +curl -s https://cim-summarizer.web.app/health | jq . +``` + +## 🎯 Best Practices + +### **Before Making Changes** +1. **Create feature branch** from current development branch +2. **Test in testing environment** first +3. **Update documentation** for any configuration changes +4. **Create backup** before major deployments + +### **Deployment Checklist** +- [ ] All tests passing +- [ ] Environment variables configured +- [ ] API keys valid +- [ ] Database migrations applied +- [ ] Documentation updated +- [ ] Backup created + +### **Code Quality** +- Use TypeScript for type safety +- Follow existing code patterns +- Add comprehensive error handling +- Include logging for debugging +- Update tests for new features + +--- + +**Last Updated**: $(date) +**Version**: 1.0 +**Maintainer**: Development Team