# ClaudeTools Reference Guide

**Purpose:** On-demand reference material for agents and deep-dive questions.
**Not loaded automatically** - agents read this when they need project details.

---

## Project Structure

```
D:\ClaudeTools/
├── api/                    # FastAPI application
│   ├── main.py            # API entry point
│   ├── models/            # SQLAlchemy models
│   ├── routers/           # API endpoints
│   ├── schemas/           # Pydantic schemas
│   ├── services/          # Business logic
│   ├── middleware/        # Auth & error handling
│   └── utils/             # Crypto utilities
├── migrations/            # Alembic database migrations
├── .claude/              # Claude Code hooks & config
│   ├── commands/         # Commands (create-spec, checkpoint)
│   ├── skills/           # Skills (frontend-design)
│   └── templates/        # Templates (app spec, prompts)
├── mcp-servers/          # MCP server implementations
│   └── feature-management/  # Feature tracking MCP server
├── scripts/              # Setup & test scripts
└── projects/             # Project workspaces
```

---

## 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
```

---

## 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

---

## Common Workflows

### 1. Create New Project

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

### 2. 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
}
```

### 3. 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

| File | Purpose |
|------|---------|
| `SESSION_STATE.md` | Complete project history and status |
| `credentials.md` | ALL infrastructure credentials (UNREDACTED) |
| `session-logs/` | Daily session documentation |
| `.env` / `.env.example` | Environment variables |
| `test_api_endpoints.py` | Phase 4 tests |
| `test_phase5_api_endpoints.py` | Phase 5 tests |
| `AUTOCODER_INTEGRATION.md` | AutoCoder resources guide |
| `TEST_PHASE5_RESULTS.md` | Phase 5 test results |

---

## Security

- **Authentication:** JWT tokens (Argon2 password hashing)
- **Encryption:** AES-256-GCM (Fernet) for credentials
- **Audit Logging:** All credential operations logged

```bash
# Get JWT Token
POST /api/auth/token
{ "email": "user@example.com", "password": "your-password" }
```

---

## Troubleshooting

```bash
# API won't start - check port
netstat -ano | findstr :8000
# Check database connection
python test_db_connection.py

# Database migration issues
alembic current        # Check current revision
alembic history        # Show migration history
alembic upgrade head   # Upgrade to latest
```

---

## MCP Servers

See `MCP_SERVERS.md` for complete details.

- **GitHub MCP** - Repository and PR management (requires token)
- **Filesystem MCP** - Enhanced file operations (D:\ClaudeTools access)
- **Sequential Thinking MCP** - Structured problem-solving

Config: `.mcp.json` | Setup: `bash scripts/setup-mcp-servers.sh`

---

## Next Steps (Optional Phase 7)

- 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.

---

## Session Log Locations

**Project-Specific:**
- Dataforth DOS: `projects/dataforth-dos/session-logs/YYYY-MM-DD-session.md`
- ClaudeTools API: `projects/claudetools-api/session-logs/YYYY-MM-DD-session.md`

**Client-Specific:** `clients/[client-name]/session-logs/YYYY-MM-DD-session.md`
**General/Mixed:** `session-logs/YYYY-MM-DD-session.md` (root)

See `PROJECT_ORGANIZATION.md` for complete structure.