claudetools/.claude/claude.md

# ClaudeTools Project Context

**Project Type:** MSP Work Tracking System with AI Context Recall
**Status:** Production-Ready (95% Complete)
**Database:** MariaDB 12.1.2 @ 172.16.3.20:3306

---

## Quick Facts

- **130 API Endpoints** across 21 entities
- **43 Database Tables** (fully migrated)
- **Context Recall System** with cross-machine persistent memory
- **JWT Authentication** on all endpoints
- **AES-256-GCM Encryption** for credentials

---

## Project Structure

```
D:\ClaudeTools/
├── api/                    # FastAPI application
│   ├── main.py            # API entry point (130 endpoints)
│   ├── models/            # SQLAlchemy models (42 models)
│   ├── routers/           # API endpoints (21 routers)
│   ├── schemas/           # Pydantic schemas (84 classes)
│   ├── services/          # Business logic (21 services)
│   ├── middleware/        # Auth & error handling
│   └── utils/             # Crypto & compression utilities
├── migrations/            # Alembic database migrations
├── .claude/              # Claude Code hooks & config
│   ├── hooks/            # Auto-inject/save context
│   └── context-recall-config.env  # Configuration
└── scripts/              # Setup & test scripts
```

---

## Database Connection

**Credentials Location:** `C:\Users\MikeSwanson\claude-projects\shared-data\credentials.md`

**Connection String:**
```
Host: 172.16.3.20:3306
Database: claudetools
User: claudetools
Password: CT_e8fcd5a3952030a79ed6debae6c954ed
```

**Environment Variables:**
```bash
DATABASE_URL=mysql+pymysql://claudetools:CT_e8fcd5a3952030a79ed6debae6c954ed@172.16.3.20:3306/claudetools?charset=utf8mb4
```

---

## Starting the API

```bash
# Activate virtual environment
api\venv\Scripts\activate

# Start API server
python -m api.main
# OR
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# Access documentation
http://localhost:8000/api/docs
```

---

## Context Recall System

### How It Works

**Automatic context injection via Claude Code hooks:**
- `.claude/hooks/user-prompt-submit` - Recalls context before each message
- `.claude/hooks/task-complete` - Saves context after completion

### Setup (One-Time)

```bash
bash scripts/setup-context-recall.sh
```

### Manual Context Recall

**API Endpoint:**
```
GET http://localhost:8000/api/conversation-contexts/recall
  ?project_id={uuid}
  &tags[]=fastapi&tags[]=database
  &limit=10
  &min_relevance_score=5.0
```

**Test Context Recall:**
```bash
bash scripts/test-context-recall.sh
```

### Save Context Manually

```bash
curl -X POST http://localhost:8000/api/conversation-contexts \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "uuid-here",
    "context_type": "session_summary",
    "title": "Current work session",
    "dense_summary": "Working on API endpoints...",
    "relevance_score": 7.0,
    "tags": ["api", "fastapi", "development"]
  }'
```

---

## Key API Endpoints

### Core Entities (Phase 4)
- `/api/machines` - Machine inventory
- `/api/clients` - Client management
- `/api/projects` - Project tracking
- `/api/sessions` - Work sessions
- `/api/tags` - Tagging system

### MSP Work Tracking (Phase 5)
- `/api/work-items` - Work item tracking
- `/api/tasks` - Task management
- `/api/billable-time` - Time & billing

### Infrastructure (Phase 5)
- `/api/sites` - Physical locations
- `/api/infrastructure` - IT assets
- `/api/services` - Application services
- `/api/networks` - Network configs
- `/api/firewall-rules` - Firewall documentation
- `/api/m365-tenants` - M365 tenant management

### Credentials (Phase 5)
- `/api/credentials` - Encrypted credential storage
- `/api/credential-audit-logs` - Audit trail (read-only)
- `/api/security-incidents` - Incident tracking

### Context Recall (Phase 6)
- `/api/conversation-contexts` - Context storage & recall
- `/api/context-snippets` - Knowledge fragments
- `/api/project-states` - Project state tracking
- `/api/decision-logs` - Decision documentation

---

## Common Workflows

### 1. Create New Project with Context

```python
# Create project
POST /api/projects
{
  "name": "New Website",
  "client_id": "client-uuid",
  "status": "planning"
}

# Initialize project state
POST /api/project-states
{
  "project_id": "project-uuid",
  "current_phase": "requirements",
  "progress_percentage": 10,
  "next_actions": ["Gather requirements", "Design mockups"]
}
```

### 2. Log Important Decision

```python
POST /api/decision-logs
{
  "project_id": "project-uuid",
  "decision_type": "technical",
  "decision_text": "Using FastAPI for API layer",
  "rationale": "Async support, automatic OpenAPI docs, modern Python",
  "alternatives_considered": ["Flask", "Django"],
  "impact": "high",
  "tags": ["api", "framework", "python"]
}
```

### 3. Track Work Session

```python
# Create session
POST /api/sessions
{
  "project_id": "project-uuid",
  "machine_id": "machine-uuid",
  "started_at": "2026-01-16T10:00:00Z"
}

# Log billable time
POST /api/billable-time
{
  "session_id": "session-uuid",
  "work_item_id": "work-item-uuid",
  "client_id": "client-uuid",
  "start_time": "2026-01-16T10:00:00Z",
  "end_time": "2026-01-16T12:00:00Z",
  "duration_hours": 2.0,
  "hourly_rate": 150.00,
  "total_amount": 300.00
}
```

### 4. Store Encrypted Credential

```python
POST /api/credentials
{
  "credential_type": "api_key",
  "service_name": "OpenAI API",
  "username": "api_key",
  "password": "sk-1234567890",  # Auto-encrypted
  "client_id": "client-uuid",
  "notes": "Production API key"
}
# Password automatically encrypted with AES-256-GCM
# Audit log automatically created
```

---

## Important Files

**Session State:** `SESSION_STATE.md` - Complete project history and status
**Documentation:**
- `.claude/CONTEXT_RECALL_QUICK_START.md` - Context recall usage
- `CONTEXT_RECALL_SETUP.md` - Full setup guide
- `TEST_PHASE5_RESULTS.md` - Phase 5 test results
- `TEST_CONTEXT_RECALL_RESULTS.md` - Context recall test results

**Configuration:**
- `.env` - Environment variables (gitignored)
- `.env.example` - Template with placeholders
- `.claude/context-recall-config.env` - Context recall settings (gitignored)

**Tests:**
- `test_api_endpoints.py` - Phase 4 tests (34/35 passing)
- `test_phase5_api_endpoints.py` - Phase 5 tests (62/62 passing)
- `test_context_recall_system.py` - Context recall tests (53 total)
- `test_context_compression_quick.py` - Compression tests (10/10 passing)

---

## Recent Work (from SESSION_STATE.md)

**Last Session:** 2026-01-16
**Phases Completed:** 0-6 (95% complete)

**Phase 6 - Just Completed:**
- Context Recall System with cross-machine memory
- 35 new endpoints for context management
- 90-95% token reduction via compression
- Automatic hooks for inject/save
- One-command setup script

**Current State:**
- 130 endpoints operational
- 99.1% test pass rate (106/107 tests)
- All migrations applied (43 tables)
- Context recall ready for activation

---

## Token Optimization

**Context Compression:**
- `compress_conversation_summary()` - 85-90% reduction
- `format_for_injection()` - Token-efficient markdown
- `extract_key_decisions()` - Decision extraction
- Auto-tag extraction (30+ tech tags)

**Typical Compression:**
```
Original: 500 tokens (verbose conversation)
Compressed: 60 tokens (structured JSON)
Reduction: 88%
```

---

## Security

**Authentication:** JWT tokens (Argon2 password hashing)
**Encryption:** AES-256-GCM (Fernet) for credentials
**Audit Logging:** All credential operations logged
**Token Storage:** `.claude/context-recall-config.env` (gitignored)

**Get JWT Token:**
```bash
# Via setup script (recommended)
bash scripts/setup-context-recall.sh

# Or manually via API
POST /api/auth/token
{
  "email": "user@example.com",
  "password": "your-password"
}
```

---

## Troubleshooting

**API won't start:**
```bash
# Check if port 8000 is in use
netstat -ano | findstr :8000

# Check database connection
python test_db_connection.py
```

**Context recall not working:**
```bash
# Test the system
bash scripts/test-context-recall.sh

# Check configuration
cat .claude/context-recall-config.env

# Verify hooks are executable
ls -l .claude/hooks/
```

**Database migration issues:**
```bash
# Check current revision
alembic current

# Show migration history
alembic history

# Upgrade to latest
alembic upgrade head
```

---

## Next Steps (Optional Phase 7)

**Remaining entities (from original spec):**
- File Changes API - Track file modifications
- Command Runs API - Command execution history
- Problem Solutions API - Knowledge base
- Failure Patterns API - Error pattern recognition
- Environmental Insights API - Contextual learning

**These are optional** - the system is fully functional without them.

---

## Quick Reference

**Start API:** `uvicorn api.main:app --reload`
**API Docs:** `http://localhost:8000/api/docs`
**Setup Context Recall:** `bash scripts/setup-context-recall.sh`
**Test System:** `bash scripts/test-context-recall.sh`
**Database:** `172.16.3.20:3306/claudetools`
**Virtual Env:** `api\venv\Scripts\activate`

---

**Last Updated:** 2026-01-16
**Project Progress:** 95% Complete (Phase 6 of 7 done)