WebAndAppMonoRepo/ARCHITECTURE.md

# Mono-Repo Structure Overview

This document provides a complete overview of the YDN mono-repo structure.

## Directory Structure

```
YDN/
│
├── services/                    # Go microservices
│   ├── api/                    # Main HTTP API server
│   │   ├── cmd/               # Application entrypoints
│   │   ├── internal/          # Private application code
│   │   │   ├── handlers/     # HTTP request handlers
│   │   │   ├── models/       # Data models
│   │   │   ├── services/     # Business logic
│   │   │   └── middleware/   # HTTP middleware
│   │   ├── go.mod            # Go module definition
│   │   └── Dockerfile        # Service Dockerfile (if custom)
│   │
│   ├── worker/                 # Background job processor
│   │   ├── cmd/
│   │   ├── internal/
│   │   │   ├── workers/      # Job handlers
│   │   │   ├── queue/        # Queue management
│   │   │   └── services/
│   │   └── go.mod
│   │
│   └── middleware/             # VPS provisioning middleware
│       ├── cmd/
│       ├── internal/
│       │   ├── providers/     # Provider implementations
│       │   ├── orchestrator/   # Provisioning logic
│       │   └── services/
│       └── go.mod
│
├── web/                        # Frontend and CMS
│   └── grav/                  # Grav CMS (flat-file PHP)
│       ├── user/              # Custom content and themes
│       ├── system/            # Grav core (gitignored)
│       ├── cache/             # Generated cache (gitignored)
│       └── logs/              # Application logs (gitignored)
│
├── backend/                    # Back-office systems
│   └── dolibarr/             # Dolibarr ERP/CRM (PHP/MySQL)
│       ├── documents/         # Document storage
│       └── custom/            # Customizations
│
├── infrastructure/              # Infrastructure as Code
│   ├── terraform/            # VM provisioning
│   │   ├── modules/         # Reusable Terraform modules
│   │   │   ├── vm/         # VM creation module
│   │   │   ├── network/     # Networking module
│   │   │   └── security/    # Security rules
│   │   ├── environments/    # Environment-specific configs
│   │   │   ├── local/       # Local KVM/QEMU testing
│   │   │   ├── staging/     # Staging environment
│   │   │   └── production/  # Production (OVH)
│   │   └── providers/       # Provider-specific configs
│   │
│   └── ansible/              # Configuration management
│       ├── playbooks/        # Ansible playbooks
│       │   ├── provision.yml # VM provisioning
│       │   ├── harden.yml    # Security hardening
│       │   ├── deploy.yml    # Application deployment
│       │   └── monitoring.yml # Monitoring setup
│       ├── roles/           # Reusable Ansible roles
│       │   ├── docker/      # Docker installation
│       │   ├── cloudron/    # Cloudron setup
│       │   ├── security/     # Security configuration
│       │   └── app/         # Application setup
│       └── inventory/        # Inventory files
│           ├── local.yml     # Local VMs
│           ├── staging.yml   # Staging instances
│           └── production.yml # Production instances
│
├── docker/                    # Docker configurations
│   ├── docker-compose.yml     # Development stack
│   ├── docker-compose.prod.yml # Production stack
│   ├── Dockerfile.api        # API service image
│   ├── Dockerfile.worker     # Worker service image
│   └── Dockerfile.middleware # Middleware service image
│
├── config/                    # Configuration files
│   ├── env/                 # Environment variable templates
│   │   ├── development.env
│   │   ├── staging.env
│   │   └── production.env
│   └── templates/           # Configuration templates
│       ├── nginx/
│       ├── app/
│       └── monitoring/
│
├── docs/                      # Documentation
│   ├── api/                 # API documentation
│   │   ├── endpoints.md
│   │   ├── authentication.md
│   │   └── examples/
│   ├── architecture/         # System architecture
│   │   ├── overview.md
│   │   ├── data-flow.md
│   │   └── security.md
│   ├── operations/           # Operational guides
│   │   ├── deployment.md
│   │   ├── monitoring.md
│   │   ├── troubleshooting.md
│   │   └── backup-restore.md
│   └── development/          # Developer docs
│       ├── setup.md
│       ├── testing.md
│       └── contribution.md
│
├── scripts/                   # Utility scripts
│   ├── deploy.sh            # Deployment automation
│   ├── test.sh              # Test runner
│   ├── backup.sh            # Backup scripts
│   ├── restore.sh           # Restore scripts
│   ├── init-local.sh        # Local environment setup
│   └── cleanup.sh           # Cleanup utilities
│
├── tests/                     # Test suites
│   ├── unit/                # Unit tests
│   │   ├── api/
│   │   ├── worker/
│   │   └── middleware/
│   ├── integration/          # Integration tests
│   │   ├── database/
│   │   ├── dolibarr/
│   │   └── stripe/
│   └── e2e/                 # End-to-end tests
│       ├── provisioning/
│       ├── payment/
│       └── customer-journey/
│
├── pkg/                       # Shared Go packages
│   ├── logger/              # Structured logging
│   ├── validator/           # Input validation
│   ├── response/            # API response helpers
│   ├── errors/              # Error handling
│   ├── database/            # Database utilities
│   ├── config/              # Configuration management
│   └── queue/               # Queue utilities
│
├── .env.example              # Environment variables template
├── .gitignore               # Git ignore rules
├── go.work                  # Go workspace file
├── Makefile                 # Common commands
├── README.md                # Project overview
├── AGENTS.md                # AI agent instructions
├── PRD.md                   # Product requirements
├── LICENSE                   # License file
└── architecture.md           # This file
```

## Component Responsibilities

### Services (Go)

**API Service** (`services/api/`)
- HTTP server and routing
- Business logic orchestration
- Request validation
- Response formatting
- Authentication/authorization

**Worker Service** (`services/worker/`)
- Background job processing
- Task queue management
- Async operations
- Email sending
- Webhook processing

**Middleware Service** (`services/middleware/`)
- VPS provisioning orchestration
- Provider abstraction
- VM lifecycle management
- Infrastructure communication

### Frontend (Grav CMS)

**Public Website** (`web/grav/`)
- Landing pages
- Product information
- Documentation
- Blog/articles
- User guides

### Backend (Dolibarr)

**ERP/CRM System** (`backend/dolibarr/`)
- Prospect management
- Customer management
- Contract management
- Invoice generation
- Support tickets
- Payment tracking

### Infrastructure

**Terraform** (`infrastructure/terraform/`)
- VM provisioning (local and production)
- Network configuration
- Security group rules
- DNS setup
- Provider abstraction

**Ansible** (`infrastructure/ansible/`)
- Post-VM configuration
- OS hardening
- Docker installation
- Cloudron setup
- Application deployment
- Monitoring configuration

### Docker

**Development Stack** (`docker/docker-compose.yml`)
- PostgreSQL
- Redis
- MySQL (Dolibarr)
- Dolibarr
- Grav CMS
- API service
- Worker service
- Middleware service

### Configuration

**Environment Management** (`config/`)
- Development environment
- Staging environment
- Production environment
- Configuration templates

### Documentation

**API Docs** (`docs/api/`)
- Endpoint specifications
- Request/response formats
- Authentication methods
- Usage examples

**Architecture** (`docs/architecture/`)
- System overview
- Data flow diagrams
- Security architecture
- Component interactions

**Operations** (`docs/operations/`)
- Deployment guides
- Monitoring setup
- Troubleshooting
- Backup/restore procedures

### Scripts

**Automation** (`scripts/`)
- Deployment automation
- Test running
- Backup management
- Environment setup
- Cleanup utilities

### Tests

**Test Coverage** (`tests/`)
- Unit tests (per component)
- Integration tests (API interactions)
- E2E tests (complete workflows)

### Shared Packages

**Common Libraries** (`pkg/`)
- Logging utilities
- Validation helpers
- Error handling
- Response formatting
- Database operations
- Queue management

## Development Workflow

1. **Local Development**
   - Start dev stack: `make dev`
   - Code changes in services
   - Run tests: `make test`

2. **VM Testing**
   - Provision local VM: `make terraform-local`
   - Configure VM: `make ansible-local`
   - Run E2E tests: `make test-e2e`

3. **Production Deployment**
   - Update terraform configs
   - Apply: `terraform apply`
   - Configure: `make ansible-production`
   - Deploy: `make deploy`

## Provider Abstraction

**Local Testing** (KVM/QEMU)
- Provider: `dmacvicar/libvirt`
- VMs on Debian 13 host
- No external dependencies

**Production** (OVH)
- Provider: `ovh/ovh`
- Same Terraform modules
- Different backend configuration
- Ansible playbooks work identically

## Key Principles

1. **Mono-Repo**: All code in single repository
2. **Containerization**: Everything in Docker
3. **Provider-Agnostic**: Easy provider swapping
4. **12-Factor**: Environment-based configuration
5. **Automation**: Terraform + Ansible + Scripts
6. **Testing**: Unit, integration, and E2E
7. **Documentation**: Comprehensive and up-to-date