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
144 lines
3.4 KiB
Markdown
144 lines
3.4 KiB
Markdown
# 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.py`
|
|
- `api/models/context_tag.py`
|
|
- `api/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
|
|
|
|
```powershell
|
|
# This script handles dependencies automatically
|
|
.\deploy.ps1
|
|
```
|
|
|
|
### Rule 3: Verify Version Match
|
|
|
|
```powershell
|
|
# 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
|
|
|
|
```powershell
|
|
# 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:
|
|
|
|
1. **Check service status:**
|
|
```bash
|
|
systemctl status claudetools-api
|
|
```
|
|
|
|
2. **Check logs:**
|
|
```bash
|
|
journalctl -u claudetools-api -n 50
|
|
```
|
|
|
|
3. **Verify files deployed:**
|
|
```bash
|
|
ls -lh /opt/claudetools/api/routers/
|
|
md5sum /opt/claudetools/api/services/conversation_context_service.py
|
|
```
|
|
|
|
4. **Rollback (if needed):**
|
|
```bash
|
|
# 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
|