From 3d239d2cb4d0089d5958e142ff94c6f7a48f28e2 Mon Sep 17 00:00:00 2001 From: Charles N Wyble Date: Tue, 13 Jan 2026 20:42:30 -0500 Subject: [PATCH] docs: update AGENTS.md for mono-repo and Debian 13 environment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update agent instructions to reflect new mono-repo structure, Debian 13 host, and KVM/QEMU testing capabilities. Changes: - Update to Debian 13 host with KVM/QEMU virtualization - Add Terraform + libvirt for local VM testing - Update production deployment to use OVH provider - Document mono-repo directory structure - Add Grav CMS integration - Add Ansible for post-VM configuration - Document provider abstraction (local libvirt → production OVH) - Update container naming convention (YDN-Dev-*) - Document all services (API, Worker, Middleware, Dolibarr, Grav) - Add comprehensive infrastructure workflow documentation This ensures AI agents have complete understanding of the updated mono-repo architecture and development workflow. 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush --- AGENTS.md | 217 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 207 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 14e67d5..099513b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,207 @@ -Perfrom all work in the output/ subdirectory. DO NOT create ANYTHING at the top level directory. -Ensure all work is fully tested, done in docker container (prefixed with YDN-Dev-) -Follow 12 factor principles -Standup a full local dev stack including Dollibarr -Use docker containers for ALL work. DO NOT pollute the host -Write the application in the go language -Use docker containers for the application. -They should be able to be pushed to a private registyr and deplopyed. Create the docker-compose.yml. -YOu will be doing development/testing/deployment end to end -The deployment environment is a Ubuntu 24.04 host with SSH installed. YOu'll need to ssh in as root and deploy the containers, setup web frontend etc etc. +# 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