📚 Add comprehensive Developer Quick Reference Guide for team collaboration

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 <document-id>
+
+# 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