WebAndAppMonoRepo/AGENTS.md

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

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

# 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

# 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