YourDreamNameHere.com/WebAndAppMonoRepo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive project documentation

Browse Source 
Add project README, architecture documentation, and detailed
setup guides for YDN mono-repo.

- README.md: Project overview and quick start guide
- ARCHITECTURE.md: Complete system architecture documentation
- docs/architecture/mono-repo-setup.md: Setup confirmation and status

Provides detailed information on:
- Mono-repo structure and component responsibilities
- Development workflow and commands
- Infrastructure setup (local KVM/QEMU and production OVH)
- Technology stack and compliance requirements

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
2026-01-13 20:41:27 -05:00
parent 967abcaa9f
commit 770d2588ed
3 changed files with 814 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

320
ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,320 @@
# 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