Enhance documentation for CI/CD, debugging, deployment, and monitoring strategies

Author: codicecustode

docs/cicd.md

@@ -19,4 +19,10 @@ If any step fails, the PR cannot be safely merged.
 - Deployment happens via SSH into Azure VM
 - Docker container is rebuilt and restarted
 
-This ensures continuous delivery with minimal manual intervention.
+This ensures continuous delivery with minimal manual intervention.
+
+
+### Deployment Safety Controls
+
+- Docker image is built and container health endpoint is validated during CI stage.
+- SSH based deployment ensures immutable infrastructure pattern where container is recreated on each release.

docs/debugging.md

@@ -1,15 +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
+1. Identify blast radius — confirm whether issue affects staging or production only.
+2. Check GitHub Actions logs to identify failing stage
+3. SSH into Azure VM
+4. Verify Docker container status using `docker ps`
+5. Check container logs using `docker logs`
+6. Validate environment variables and port bindings
+7. Test application health endpoint locally inside VM
+8. Rollback to last working commit using `git revert`
+9. Rebuild Docker image and restart container
+10. Monitor logs after redeployment
 
 This structured approach minimizes downtime and ensures faster recovery.

docs/deployment.md

@@ -26,4 +26,17 @@ 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
+- GitHub Actions workflow can be re-run
+
+### Container Versioning Strategy
+
+Each deployment can optionally tag Docker images using commit SHA.
+This enables deterministic rollback by redeploying a previous image tag.
+
+### Runtime Architecture
+
+- Single Azure VM hosts two isolated Docker containers.
+- Production container binds to port 8000.
+- Staging container binds to port 8001.
+- Nginx acts as reverse proxy routing external traffic.
+- CI pipeline performs remote deployment via SSH automation.

docs/monitoring.md

@@ -33,4 +33,10 @@
 
 - GitHub Secrets
 - Azure Key Vault
-- Avoid storing secrets in codebase
+- Avoid storing secrets in codebase
+
+### Metrics and Alerting
+
+- CPU and memory utilization can be monitored via Azure Monitor.
+- Health endpoint failure alerts can be configured.
+- Log aggregation systems such as ELK / Datadog can provide anomaly detection.