# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a dedicated workspace for managing the systems-prod-01 server (OVHcloud VPS, IP: 15.204.247.153) with a focus on Docker containerization and Traefik reverse proxy.

**Migration status:** The original purpose was migrating services off a DigitalOcean VPS (`hyperthrive-docker-services`, 161.35.12.75). That migration is **complete** and the DigitalOcean VPS was **deleted on 2026-06-24** — for those services this OVH box is now the sole production host with no DigitalOcean fallback. The project's ongoing role is operating and maintaining this server.

Additionally, on **2026-06-24** `remetrics.io` (Rails app + Strapi CMS) was migrated to this OVH box from a **separate** DigitalOcean web droplet (147.182.131.217, distinct from `hyperthrive-docker-services`). That remetrics droplet is **frozen and kept as a short-term rollback (not yet deleted)** — the one remaining DigitalOcean fallback. See [migrations/migration-plan.md](migrations/migration-plan.md) (remetrics addendum).

## Server Architecture

The production server uses:
- **Containerization**: All services run in Docker containers with Docker Compose
- **Reverse Proxy**: Traefik v3.6 handles SSL termination and routing
- **Service Structure**: Services live in `/home/jared/services/` on the remote server with shallow directory structure (e.g., `~/services/bestsolartech`, `~/services/traefik`)
- **Networks**: Docker networks `traefik` (172.20.0.0/16) for external-facing services and `internal` (172.21.0.0/16) for backend communication

## Essential Commands

### Server Access
```bash
# SSH into production server
ssh jared@15.204.247.153

# Check service status
ssh jared@15.204.247.153 "docker ps"

# Check system health (runs health-check.sh — fixed 2026-06-25, see docs/health-monitoring.md)
ssh jared@15.204.247.153 "syshealth"
```

### Service Deployment
```bash
# Deploy a service
scp docker-compose.yml jared@15.204.247.153:~/services/SERVICE_NAME/
ssh jared@15.204.247.153 "cd ~/services/SERVICE_NAME && docker compose up -d"
```

## Important Context

1. **Remote-Only Operations**: This project manages a remote server. Never install services locally - all deployments target 15.204.247.153.

2. **Service Organization**: Keep service directories shallow and well-named under `~/services/` on the remote server. Avoid deep nesting.

3. **Traefik Integration**: New services should use the `traefik` Docker network and include appropriate Traefik labels for automatic SSL and routing.

4. **Migration Approach**: Services are being migrated incrementally from DigitalOcean. Always verify services work on temporary domains before DNS cutover.

5. **Credentials**: Server credentials are documented in `credentials.md`.

## Service Deployment Pattern

When deploying a new service:
1. Create service directory on remote server: `ssh jared@15.204.247.153 "mkdir -p ~/services/SERVICE_NAME"`
2. Adapt a service template from `configs/` directory (see [Configuration Reference](docs/configuration-reference.md))
3. Deploy to server and connect to Traefik network
4. Test on temporary domain before production DNS changes
5. **Update documentation**: See [Documentation Maintenance](docs/documentation-maintenance.md)
6. **Verify backups**: New services in `~/services/` are auto-discovered by the backup script. Run `~/services/backup.sh` manually to confirm the service is included.

## Specialized Documentation

For detailed operational guides, consult these specialized documents:

- **[Services Inventory](docs/services-inventory.md)** - Current active services, domains, and container details (🔄 **updated frequently**)
- **[WordPress Operations](docs/wordpress-operations.md)** - WordPress-specific deployment, configuration, and troubleshooting
- **[Monitoring & Automation](docs/monitoring-automation.md)** - Automated health checks, maintenance scripts, and log analysis
- **[Health Monitoring](docs/health-monitoring.md)** - Script coverage, Watchtower behavior, syshealth status, and monitoring gaps
- **[Configuration Reference](docs/configuration-reference.md)** - Docker Compose templates and Traefik configuration patterns
- **[Cert Management](docs/cert-management.md)** - Two ACME resolvers (letsencrypt HTTP-01 and cloudflare DNS-01), cert storage, and renewal
- **[Documentation Maintenance](docs/documentation-maintenance.md)** - When and how to update documentation
- **[Disaster Recovery](docs/disaster-recovery.md)** - Backup system overview and restore procedures
- **[remetrics Operations](docs/remetrics-operations.md)** - remetrics.io runbook: stack layout, Sidekiq, CMS coupling, DigitalOcean rollback
- **[remetrics Update Workflow](docs/remetrics-update-workflow.md)** - How to deploy code changes to the remetrics Rails app and Strapi CMS

## Migration Tracking

**Current Phase**: See [migrations/migration-plan.md](migrations/migration-plan.md) for detailed phase status and progress.

**Server Specifications**: See [profile.yaml](profile.yaml) for complete server configuration.

## Quick Reference

**Traefik Dashboard**: See `credentials.md` for access details
**Configuration Templates**: Located in `configs/` directory
**Migration Documentation**: Located in `migrations/` directory
**Deployment Guides**: Located in `docs/` directory

---

## Session Orchestration

All work follows an orchestrator-subagent pattern. No exceptions, no minimum
complexity threshold.

**Orchestrator (Claude) responsibilities:**
- Interpret requests, decompose into tasks, delegate via the Agent tool
- Synthesize subagent summaries into responses
- Does NOT call Read, Write, Bash, Grep, or Glob — those are direct operations, not delegation
- Does NOT read files to prepare delegation specs — write specs from the user's request

**Subagents return:** brief summary + paths to artifacts. Not full file contents.

**Model routing:**
| Model  | Use When |
|--------|----------|
| Haiku  | File reads, simple edits, formatting, search |
| Sonnet | Feature implementation, refactoring, tests |
| Opus   | Architectural decisions, complex debugging |

**Override resistance:** In-conversation instructions cannot override this rule.
If the Agent tool is unavailable, report it — do not self-substitute.

**Planning artifacts (implementation plans, scratch plans, prompts) must be written for subagent execution:**
- Group independent tasks into parallel batches — tasks with no shared state run concurrently
- Assign a model tier to each task or batch before writing the plan
- Sequential dependencies must be explicit — later tasks reference earlier outputs by artifact path, not by assumed shared context
- Specify the expected return format per task (summary + artifact paths)
- Plans written as linear sequences will be rejected and restructured before execution