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