Mike Swanson
a6eedc1b77
- Add /api/version endpoint with git commit and file checksums - Create automated deploy.ps1 script with pre-flight checks - Document file dependencies to prevent partial deployments - Add version verification before and after deployment Prevents: 4-hour debugging sessions due to production/local mismatch Ensures: All dependent files deploy together atomically Verifies: Production matches local code after deployment
3.4 KiB
3.4 KiB
ClaudeTools File Dependencies
CRITICAL: These files must be deployed together. Deploying only some files will cause runtime errors.
Context Recall System
Router Layer:
api/routers/conversation_contexts.py
Service Layer (MUST deploy with router):
api/services/conversation_context_service.py
Model Layer (MUST deploy if schema changes):
api/models/conversation_context.pyapi/models/context_tag.pyapi/models/__init__.py
Why they're coupled:
- Router calls service layer methods with specific parameters
- Service layer returns model objects
- Changing router parameters requires matching service changes
- Model changes affect both service and router serialization
Symptom of mismatch:
Failed to retrieve recall context: get_recall_context() got an unexpected keyword argument 'search_term'
Version System
Router:
api/routers/version.py
Main App (MUST deploy with version router):
api/main.py
Why they're coupled:
- Main app imports and registers version router
- Missing import causes startup failure
Deployment Rules
Rule 1: Always Deploy Related Files Together
When modifying:
- Router → Also deploy matching service file
- Service → Check if router uses it, deploy both
- Model → Deploy router, service, and model files
Rule 2: Use Automated Deployment
# This script handles dependencies automatically
.\deploy.ps1
Rule 3: Verify Version Match
# Check local version
git rev-parse --short HEAD
# Check production version
curl http://172.16.3.30:8001/api/version | jq .git_commit_short
Rule 4: Test After Deploy
# Test recall endpoint
curl -H "Authorization: Bearer $JWT" \
"http://172.16.3.30:8001/api/conversation-contexts/recall?search_term=test&limit=1"
Complete File Dependency Map
api/main.py
├── api/routers/version.py (REQUIRED)
├── api/routers/conversation_contexts.py (REQUIRED)
│ ├── api/services/conversation_context_service.py (REQUIRED)
│ │ └── api/models/conversation_context.py (REQUIRED)
│ └── api/schemas/conversation_context.py (REQUIRED)
└── ... (other routers)
api/services/conversation_context_service.py
├── api/models/conversation_context.py (REQUIRED)
├── api/models/context_tag.py (if using normalized tags)
└── api/utils/context_compression.py (REQUIRED)
Checklist Before Deploy
- All local changes committed to git
- Local tests pass
- Identified all dependent files
- Verified version endpoint exists
- Deployment script ready
- Database migrations applied (if any)
- Backup of current production code (optional)
Recovery from Bad Deploy
If deployment fails:
- Check service status:
systemctl status claudetools-api
- Check logs:
journalctl -u claudetools-api -n 50
- Verify files deployed:
ls -lh /opt/claudetools/api/routers/
md5sum /opt/claudetools/api/services/conversation_context_service.py
- Rollback (if needed):
# Restore from backup or redeploy last known good version
git checkout <previous-commit>
.\deploy.ps1 -Force
Generated: 2026-01-18 Last Updated: After 4-hour debugging session due to code mismatch Purpose: Prevent deployment issues that waste development time