Merge pull request #1 from codicecustode/develop

PR from develop to main

Author: codicecustode

docs/branching.md

@@ -0,0 +1,31 @@
+## Branching Strategy
+
+This project follows a structured Git branching model:
+
+- `main` → Production environment
+- `develop` → Staging / integration environment
+- `feature/*` → Feature development branches
+
+### Workflow
+
+1. Developer creates a feature branch from `develop`
+2. Feature is implemented and pushed
+3. Pull Request is created to `develop`
+4. CI pipeline validates build and container health
+5. After approval, feature is merged into `develop`
+6. Release Pull Request is created from `develop` to `main`
+7. On merge to `main`, production deployment is triggered
+
+### Conflict Resolution Approach
+
+Before merging, the feature branch is rebased or merged with latest `develop` branch.
+Conflicts are resolved locally, tested again, and then pushed.
+
+### Branch Protection Strategy
+
+Even though GitHub free plan does not enforce strict protection:
+
+- Direct push to `main` is avoided
+- Pull Request approval is required
+- CI pipeline must pass before merge
+- Feature branches are short-lived

docs/cicd.md

@@ -0,0 +1,22 @@
+## CI/CD Pipeline Flow
+
+CI/CD is implemented using GitHub Actions.
+
+### CI Flow
+
+- Pipeline triggers on Pull Requests to `develop` and `main`
+- Dependencies are installed
+- Syntax validation is performed
+- Docker image build is tested
+- Container health endpoint is validated
+
+If any step fails, the PR cannot be safely merged.
+
+### CD Flow
+
+- Push to `develop` triggers staging deployment
+- Push to `main` triggers production deployment
+- Deployment happens via SSH into Azure VM
+- Docker container is rebuilt and restarted
+
+This ensures continuous delivery with minimal manual intervention.

docs/debugging.md

@@ -0,0 +1,15 @@
+## Production Deployment Failure Debugging Approach
+
+If production deployment fails after merge:
+
+1. Check GitHub Actions logs to identify failing stage
+2. SSH into Azure VM
+3. Verify Docker container status using `docker ps`
+4. Check container logs using `docker logs`
+5. Validate environment variables and port bindings
+6. Test application health endpoint locally inside VM
+7. Rollback to last working commit using `git revert`
+8. Rebuild Docker image and restart container
+9. Monitor logs after redeployment
+
+This structured approach minimizes downtime and ensures faster recovery.

docs/deployment.md

@@ -0,0 +1,29 @@
+## Deployment Architecture
+
+Application is deployed on an Azure Virtual Machine using Docker.
+
+Two environments are maintained on the same VM:
+
+- Staging → Container running on port 8001 (develop branch)
+- Production → Container running on port 8000 (main branch)
+
+Nginx reverse proxy routes traffic to appropriate containers.
+
+### Environment Variable Management
+
+Sensitive values are not stored in the repository.
+
+They are managed using:
+
+- GitHub Secrets for CI/CD authentication
+- Environment variables inside Docker runtime
+- Azure Key Vault can be used in real production
+
+### Rollback Strategy
+
+If deployment fails:
+
+- Previous commit can be reverted
+- Older Docker image can be redeployed
+- Container can be restarted with previous tag
+- GitHub Actions workflow can be re-run

docs/monitoring.md

@@ -0,0 +1,36 @@
+## Monitoring and Infrastructure Strategy
+
+### Logging
+
+- Application logs are collected via `docker logs`
+- Nginx access logs help identify traffic patterns
+- Azure Monitor / ELK stack can be integrated for centralized logging
+
+### Downtime Handling
+
+- Docker container restart policies improve resilience
+- Healthcheck endpoint ensures service availability
+- Load balancer can be added for redundancy
+
+### Scaling Strategy
+
+- Horizontal scaling using multiple containers
+- VM Scale Sets or Kubernetes for auto-scaling
+- Stateless architecture to allow scaling
+
+### API Credit Monitoring
+
+- Middleware can track API usage
+- Threshold alerts can notify via email or Slack
+
+### Cost Optimization
+
+- Use smaller VM size for staging
+- Schedule non-production shutdown during low usage
+- Use autoscaling to match demand
+
+### Secrets Management
+
+- GitHub Secrets
+- Azure Key Vault
+- Avoid storing secrets in codebase