docs: rewrite README to lead with pipeline architecture and design decisions

Author: darestack

README.md

@@ -1,141 +1,99 @@
-# GitHub Actions EC2 Pipeline
+# github-actions-ec2-pipeline
 
-A simple Node.js application with a CI/CD pipeline using GitHub Actions to deploy to an EC2 instance.
+> GitHub Actions pipeline that builds, tests, versions, and deploys a Node.js app
+> to AWS EC2 — zero manual steps after initial setup.
 
-This project is a demonstration of how to set up a full CI/CD pipeline for a Node.js application. It includes a simple Express application, a set of tests, and a GitHub Actions workflow that automatically builds, tests, and deploys the application to an AWS EC2 instance.
+[![CI Pipeline](https://github.com/darestack/github-actions-ec2-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/darestack/github-actions-ec2-pipeline/actions/workflows/ci.yml)
 
-## Features
+---
 
-- **Node.js Express Application:** A simple REST API with a few endpoints.
-- **CI/CD Pipeline:** A GitHub Actions workflow that automates the entire build, test, and deployment process.
-- **Zero-Downtime Deployment:** The deployment script uses `pm2 reload` to ensure that the application is always available, even during deployments.
-- **Rollback Mechanism:** The deployment script automatically creates a backup of the previous release. If a deployment fails, it automatically rolls back to the previous version.
-- **Automated Versioning and Releases:** The pipeline automatically bumps the version number, creates a tag, and generates a GitHub release.
-- **Health Checks:** The CI/CD pipeline includes a health check step to ensure that the application is running correctly after a deployment.
-- **Monitoring:** A separate GitHub Actions workflow runs every 5 minutes to check the health of the application and sends a notification if it's down.
+## Pipeline Overview
 
-## CI/CD Pipeline
-
-The CI/CD pipeline is split into two workflows: `ci.yml` for Continuous Integration and `release.yml` for Continuous Deployment.
-
-### `ci.yml` - Continuous Integration
-
-This workflow runs on every push to the `main`, `development`, and `feature/*` branches. It consists of two jobs:
-
-1.  **`build-and-test`:** This job builds the application and runs the test suite.
-2.  **`bump-version`:** This job runs only on the `main` branch after the `build-and-test` job succeeds. It automatically bumps the patch version of the application and creates a new Git tag (e.g., `v1.0.1`). The tagging step uses a Personal Access Token stored as `REPO_ACCESS_TOKEN`.
-
-### `release.yml` - Continuous Deployment
-
-This workflow is triggered whenever a new tag is pushed to the repository (tags starting with 'v\*'). It consists of two jobs:
-
-1. **`deploy`:**
-
-   - Checks out the code
-   - Sets up deployment environment variables from GitHub secrets
-   - Creates a deployment package (tar.gz)
-   - Deploys to EC2 using SSH:
-     - Copies the package to /tmp/
-     - Executes the deployment script at /var/www/app/scripts/deploy.sh
-
-2. **`create-release`:**
-   - Runs after successful deployment
-   - Creates a GitHub Release with the tag name using `GITHUB_TOKEN` and `permissions: contents: write`
-
-To trigger this workflow:
-
-```bash
-git tag v1.0.0
-git push origin v1.0.0
 ```
-
-### Deployment Diagram
-
-```mermaid
-graph TD
-    A[Push to main] --> B{CI Workflow};
-    B --> C[Build and Test];
-    C --> D[Bump Version & Create Tag];
-    D --> E{Release Workflow};
-    E --> F[Deploy to Production];
-    F --> G[Create GitHub Release];
+Push to main / feature branch
+  │
+  └── ci.yml
+        ├── build-and-test: npm ci → Jest tests → pass/fail gate
+        └── bump-version (main only): patch version bump → git tag v1.x.x
+                │
+                └── release.yml (triggered by tag v*)
+                      ├── deploy: tar.gz → SCP to EC2 → deploy.sh (PM2 reload, atomic symlink swap)
+                      └── create-release: GitHub Release with changelog
 ```
 
-## Technologies Used
+### Key Design Decisions
 
-- **Node.js 20.x (LTS)**
-- **Express**
-- **Jest** for testing
-- **GitHub Actions** for CI/CD
-- **AWS EC2** for hosting
-- **PM2** for process management
-- **Bootstrap** for the frontend
+| Decision | Implementation | Why |
+|---|---|---|
+| **Zero-downtime deploy** | `pm2 reload` + atomic symlink swap (`current → release-timestamp`) | App stays up during deployment; rollback is a symlink change |
+| **Auto-rollback** | `deploy.sh` keeps previous release; restores on failure | No manual intervention if deploy breaks the app |
+| **Automatic versioning** | `bump-version` job creates `v1.x.x` tags on every merge to main | Release history is automatic; no manual tagging |
+| **Health check monitoring** | Scheduled workflow every 5 min; creates a GitHub Issue on failure | On-call alert without a third-party service |
+| **Separate CI / CD workflows** | `ci.yml` + `release.yml` split by tag trigger | CD only runs on verified, tagged builds — not every push |
 
-## Local Setup
+---
 
-1.  Clone the repository:
+## Workflows
 
-    ```bash
-    git clone https://github.com/daretechie/github-actions-ec2-pipeline.git
-    ```
+### `ci.yml` — Continuous Integration
+Triggers: push to `main`, `development`, `feature/*` branches + all PRs
 
-2.  Install the dependencies:
+1. **`build-and-test`**: `npm ci` → Jest test suite → pass required before merge
+2. **`bump-version`** (main only): increments patch version, pushes `v1.x.x` tag — triggers `release.yml`
 
-    ```bash
-    npm install
-    ```
+### `release.yml` — Continuous Deployment  
+Triggers: new tag matching `v*`
 
-3.  Start the application:
+1. **`deploy`**: packages build → SCP to EC2 → runs `/var/www/app/scripts/deploy.sh`
+   - Installs dependencies in release dir → atomic symlink `current` → `pm2 reload`
+   - On failure: restores previous symlink → `pm2 reload` (auto-rollback)
+2. **`create-release`**: publishes GitHub Release with tag name
 
-    ```bash
-    npm start
-    ```
+### `health-check.yml` — Uptime Monitoring
+Runs every 5 minutes. Hits `/api/health`. Creates a GitHub Issue if the check fails.
 
-4.  The application will be available at `http://localhost:3000`.
+---
 
-## Configuration
+## Required GitHub Secrets
 
-The CI/CD pipeline requires the following secrets to be set in the GitHub repository:
+| Secret | Purpose |
+|---|---|
+| `PROD_EC2_HOST` | Production EC2 hostname or IP |
+| `PROD_EC2_USER` | SSH username |
+| `PROD_EC2_KEY` | Private SSH key (PEM format) |
+| `REPO_ACCESS_TOKEN` | PAT with `repo` scope — needed for `bump-version` to push tags |
 
-- `PROD_EC2_HOST`: The hostname or IP address of the production EC2 instance.
-- `PROD_EC2_USER`: The username for the production EC2 instance.
-- `PROD_EC2_KEY`: The private SSH key for the production EC2 instance.
-- `DEV_EC2_HOST`: The hostname or IP address of the development EC2 instance.
-- `DEV_EC2_USER`: The username for the development EC2 instance.
-- `DEV_EC2_KEY`: The private SSH key for the development EC2 instance.
-- `REPO_ACCESS_TOKEN`: A Personal Access Token (classic) with `repo` scope. This is required for the `bump-version` job to create tags that trigger `release.yml`.
+Also set: **Actions → General → Workflow permissions → Read and write** (allows built-in token to create releases and issues).
 
-Optional:
-- `HEALTHCHECK_ISSUE_TOKEN`: A Personal Access Token (classic) with `repo` scope if you prefer creating issues from the scheduled health-check with a PAT instead of the built-in token.
+---
 
-Repository Settings → Actions → General:
-- Set Workflow permissions to “Read and write permissions” to allow the built-in token to create releases and issues.
+## Application Stack
 
-## Health Check and Monitoring
+`Node.js 20 LTS` · `Express` · `Jest` · `PM2` · `GitHub Actions` · `AWS EC2`
 
-- Health endpoint: `/api/health`.
-- Workflow: `.github/workflows/health-check.yml` runs every 5 minutes and can be run manually via “Run workflow”.
-- On failure, it creates an issue in the repository (requires write permissions as noted above).
+---
 
-## Deployment and Access
+## Local Setup
 
-- Zero-downtime releases with PM2: the deploy script runs the app via the stable symlink `current/src/server.js` and swaps releases atomically.
-- The app listens on `0.0.0.0:3000`. You can access it at:
-  - `http://YOUR_EC2_PUBLIC_IP:3000/`
-  - `http://YOUR_EC2_PUBLIC_IP:3000/api/health`
-- If you prefer port 80/443, add an Nginx reverse proxy in front of the app. Example server block (HTTP only):
+```bash
+git clone https://github.com/darestack/github-actions-ec2-pipeline.git
+cd github-actions-ec2-pipeline
+npm install
+npm test
+npm start
+# → http://localhost:3000
+# → http://localhost:3000/api/health
+```
 
+To add Nginx as a reverse proxy on the EC2 instance (port 80 → 3000):
 ```nginx
 server {
     listen 80;
     server_name _;
-
     location / {
         proxy_pass http://127.0.0.1:3000;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
     }
 }
 ```