# 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