# YDN Agent Instructions

## Project Overview
YDN is a mono-repo SaaS platform providing sovereign hosting stacks for $250/month per domain.
Customer provides credit card, domain name, email address → receives OVH domain, OVH VPS, Cloudron, DNS integration.

## Development Environment
- **Host**: Debian 13 with KVM/QEMU virtualization
- **Testing**: Terraform + libvirt provider for local VM provisioning
- **Production**: Swap to real providers (OVH initially)
- **Approach**: 12-factor principles, containerized services

## Mono-Repo Structure
```
/home/charles/Projects/YDN/
├── services/                    # Go microservices
│   ├── api/                    # Main HTTP API server
│   ├── worker/                 # Background job processor
│   └── middleware/             # VPS provisioning middleware
├── web/                        # Grav CMS (public website)
├── backend/                     # Dolibarr (ERP/CRM)
├── infrastructure/               # IaC and automation
│   ├── terraform/              # VM provisioning (local + production)
│   │   ├── modules/            # Reusable Terraform modules
│   │   ├── environments/       # Local, staging, production configs
│   │   └── providers/          # libvirt (local), ovh (production)
│   └── ansible/                # Post-VM creation configuration
│       ├── playbooks/          # Ansible playbooks
│       ├── roles/              # Ansible roles
│       └── inventory/          # Dynamic inventory scripts
├── docker/                     # Docker configurations
│   ├── docker-compose.yml      # Development stack
│   ├── docker-compose.prod.yml # Production stack
│   └── Dockerfile.*            # Service Dockerfiles
├── config/                     # Configuration files
│   ├── env/                   # Environment-specific configs
│   └── templates/             # Config templates
├── docs/                       # Documentation
│   ├── api/                   # API documentation
│   ├── architecture/           # Architecture docs
│   └── operations/            # Operational guides
├── scripts/                    # Utility scripts
│   ├── deploy.sh             # Deployment automation
│   ├── test.sh               # Test runner
│   └── backup.sh             # Backup scripts
├── tests/                      # Test suites
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── e2e/                  # End-to-end tests
├── go.work                     # Go workspace file (for mono-repo)
├── Makefile                    # Common commands
├── README.md                   # Project overview
├── PRD.md                      # Product requirements
└── AGENTS.md                   # This file
```

## Technology Stack

### Core Services (Go)
- **services/api**: Main HTTP server, business logic, orchestration
- **services/worker**: Background job processing, async tasks
- **services/middleware**: VPS provisioning abstraction layer

### CMS (Grav)
- **web/grav**: Flat-file CMS for public website, documentation
- Docker containerized
- Integrates with API for dynamic content

### ERP/CRM (Dolibarr)
- **backend/dolibarr**: Complete business management
- Prospects, customers, contracts, invoices, support tickets
- Docker containerized with MySQL

### Infrastructure
- **terraform**: Multi-provider abstraction
  - Local testing: `dmacvicar/libvirt` provider (KVM/QEMU on Debian 13)
  - Production: `ovh/ovh` provider
  - Modules: VM provisioning, networking, security
- **ansible**: Post-VM configuration
  - OS hardening
  - Docker installation
  - Cloudron deployment
  - DNS configuration
  - Security setup

### Deployment Targets
- **Development**: Debian 13 host with KVM/QEMU (Terraform + libvirt)
- **Production**: OVH infrastructure (Terraform + OVH provider)
- Swap providers via Terraform backend configuration

## Development Workflow

### 1. Local Development
```bash
# Start development stack
docker-compose -f docker/docker-compose.yml up -d

# Run Go services in containers
# All services prefixed with YDN-Dev-
```

### 2. VM Testing (Local)
```bash
# Provision test VM via Terraform
cd infrastructure/terraform/environments/local
terraform apply

# Configure VM via Ansible
cd ../../../ansible
ansible-playbook -i inventory/local.yml playbooks/provision.yml
```

### 3. Production Deployment
```bash
# Switch to production provider
cd infrastructure/terraform/environments/production
terraform apply

# Ansible for post-creation config
cd ../../../ansible
ansible-playbook -i inventory/production.yml playbooks/provision.yml
```

## Key Principles

### Mono-Repo Management
- All services in single repository
- Go workspace for module management
- Shared packages in `pkg/` directory
- Coordinated releases via tags

### Provider Abstraction
- Terraform modules are provider-agnostic
- Swap local libvirt for production providers
- Ansible playbooks work across all environments
- Same configuration, different backend

### Containerization
- EVERYTHING in Docker containers
- Container names: `YDN-Dev-*` (dev), `YDN-Prod-*` (prod)
- Private registry for deployment
- No host pollution

### Testing
- Integration tests use local VMs
- E2E tests with full stack
- Mock external APIs (Stripe, OVH) where needed
- Accessibility testing (WCAG 2.1 AA)

### Dolibarr Integration (CRITICAL)
- ALL business operations go through Dolibarr
- Prospects created on email verification
- Customers converted on payment
- Contracts, invoices, support tickets
- API integration mandatory

### VPS Provisioning
1. Terraform provisions VM (local libvirt or production OVH)
2. Ansible configures post-creation (OS, Docker, Cloudron)
3. Middleware service orchestrates entire flow
4. Status tracked via API

## Deployment Process

### Development
1. Code changes in appropriate service directory
2. Test locally with `docker-compose`
3. Deploy to staging environment
4. Integration tests with Terraform + Ansible

### Production
1. Update terraform environment configs
2. `terraform apply` for VM provisioning
3. `ansible-playbook` for configuration
4. Deploy Go services via `scripts/deploy.sh`
5. Monitor via Dolibarr + API metrics

## CI/CD Pipeline (Future)
- Automated testing on push
- Terraform validation
- Ansible syntax checking
- Go tests + linting
- Security scanning
- Deploy to staging
- Manual approval for production

## Security
- All secrets in environment variables or secret managers
- SSH keys managed via Ansible Vault
- TLS/SSL for all services
- Firewall rules via Terraform + Ansible
- Regular backups (automated)

## Accessibility
- WCAG 2.1 AA compliance for all web interfaces
- Grav CMS: accessible templates
- API: proper error messages
- Documentation: screen reader compatible

## Important Notes
- NEVER create files outside designated mono-repo structure
- ALWAYS use Docker containers for services
- PROVIDER SWAP is key capability (test locally, deploy to prod)
- DOLIBARR integration is non-negotiable
- ANSIBLE handles all post-VM configuration
- TERRAFORM handles VM provisioning
- MIDDLEWARE orchestrates VPS lifecycle