docs: update AGENTS.md for mono-repo and Debian 13 environment

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 <crush@charm.land>
2026-01-13 20:42:30 -05:00
parent 75cff49e85
commit 3d239d2cb4
1 changed files with 207 additions and 10 deletions
--- 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