3d239d2cb4
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>
208 lines
7.2 KiB
Markdown
208 lines
7.2 KiB
Markdown
# 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
|