HealthPulse Portal — Complete Capstone Project

 

HealthPulse Portal — Complete Capstone Project

*HealthPulse Inc.** is a healthcare technology startup that has built a patient portal as a **React/TypeScript single-page application**. The application allows patients to view appointments, lab results, medications, and communicate with their care team.

Currently, the development team **manually builds and deploys** the application by:

1. Running `npm run build` on a developer's laptop

2. SCP-ing the `dist/` folder to a single Nginx server

3. SSHing into the server and restarting Nginx

and hosted by their private server

https://healthpulse-capstone.vercel.app/

This process takes **45 minutes per deployment**, is error-prone, and has caused **3 production outages** in the last quarter from misconfigurations. There is **no testing in the pipeline**, **no code quality checks**, **no security scanning**, and **no monitoring**.

**HealthPulse Inc. has hired your DevOps team** to design and implement a complete CI/CD pipeline, multi-environment infrastructure, container orchestration, and observability platform on **AWS**.

---

## Application Details

| Item | Detail |

|------|--------|

| **App Name** | HealthPulse Portal |

| **Tech Stack** | React 18, TypeScript, Vite, shadcn/ui, Tailwind CSS |

| **Testing** | Vitest (unit), Playwright (e2e) |

| **Build Output** | Static files (`dist/`) served by Nginx |

| **Container** | Multi-stage Dockerfile (Node build → Nginx serve) |

| **Health Endpoint** | `GET /health` → `{"status":"healthy"}` |

Stack: React 18 + TypeScript + Vite + shadcn/ui + Tailwind CSS + Recharts

## Repository Structure

healthpulse-capstone/

├── src/                        # Application source code

│   ├── components/ui/          # shadcn/ui components

│   ├── components/layout/      # Layout (Sidebar, Header)

│   ├── pages/                  # Login, Dashboard, Appointments, LabResults, etc.

│   ├── data/                   # Mock data

│   ├── types/                  # TypeScript types

│   ├── lib/                    # Utilities

│   └── test/                   # Unit tests

├── tests/e2e/                  # Playwright e2e tests

## Tools & Technologies

| Category | Tool | Purpose |

|----------|------|---------|

| **CI/CD** | Jenkins OR GitLab CI OR Azure DevOps | Pipeline automation (student chooses one) |

| **Cloud** | AWS (ECS Fargate, ALB, VPC, Route 53) | Infrastructure hosting |

| **IaC** | Terraform | Infrastructure provisioning |

| **Config Mgmt** | Ansible Tower | Application deployment & rollback |

| **Containers** | Docker | Application containerization |

| **Orchestration** | Kubernetes (EKS) | Container orchestration |

| **Artifact Repo** | JFrog Artifactory | Docker images + build artifacts |

| **Code Quality** | SonarQube | Static analysis + code coverage |

| **Security** | Snyk | Dependency vulnerability scanning |

| **Monitoring** | Datadog | Infrastructure + application monitoring |

| **Version Control** | Git (Bitbucket/GitHub/GitLab) | Source code management |

---

### TASK A: Documentation Platform (Docs-as-Code)

Set up a **MkDocs Material** documentation site using the docs-as-code approach. Documentation lives in the Git repository as Markdown files and is built/served via Docker.

#### Why Docs-as-Code?

This is how top DevOps teams (AWS, Kubernetes, Terraform) manage documentation — Markdown files in Git, built by CI, deployed as a static site. You'll use the same multi-stage Docker pattern as the main application.

| Requirement | Detail |

|-------------|--------|

| Tool | MkDocs with Material theme |

| Container Port | `84` |

| Build | Multi-stage Docker (mkdocs build → nginx serve) |

| Dev Mode | `mkdocs serve` with live reload on port `8084` |

| Location | `docs/` directory in the deployment repo |

New File	Purpose
docs/mkdocs.yml	MkDocs config with Material theme, dark/light toggle, nav, extensions
docs/Dockerfile	Multi-stage build (mkdocs-material → nginx:alpine)
docs/docker-compose.yml	Prod on port 84 + live-reload dev mode on port 8084
docs/docs/index.md	Home page with project overview, team roster template
docs/docs/architecture.md	ADR templates (CI/CD platform + container orchestration)
docs/docs/environments.md	Environment matrix table (Dev/UAT/QA/Prod)
docs/docs/runbooks.md	4 runbook templates (deploy, rollback, scale, incident)
docs/docs/pipeline.md	CI/CD pipeline stage docs with diagrams

#### Required Documentation Pages

| Page | Content |

|------|---------|

| Home (`index.md`) | Project overview, team roster, quick links |

| Architecture Decisions (`architecture.md`) | ADR-001: CI/CD Platform choice, ADR-002: Container orchestration choice |

| Environment Matrix (`environments.md`) | Dev/UAT/QA/Prod table with IPs, URLs, instance sizes |

| Runbooks (`runbooks.md`) | Deploy, rollback, scale, incident response procedures |

| CI/CD Pipeline (`pipeline.md`) | Pipeline stages, tools, configuration notes |

#### Commands

```bash

# Build and serve docs (production)

cd docs && docker-compose up docs-prod

# → Docs at http://localhost:84

# Live reload dev mode

cd docs && docker-compose up docs-dev

# → Docs at http://localhost:8084 (auto-refreshes on file save)

```

**Acceptance Criteria:**

- [ ] MkDocs site builds via multi-stage Dockerfile

- [ ] Docs served on port 84 via docker-compose

- [ ] Live reload dev mode working on port 8084

- [ ] All 5 documentation pages created with real content

- [ ] `mkdocs.yml` and all Markdown files committed to Git

- [ ] Docs auto-build in CI pipeline on changes to `docs/` folder

Summary Task A 

TASK A: Documentation Platform (Docs-as-Code)

1. Set up MkDocs with Material theme inside the deployment repo
2. Create a docker-compose.yml to serve docs on port 84
3. Write initial documentation pages:
   - Team roster and roles
   - ADR: "Why we chose [Jenkins/GitLab/Azure DevOps]"
   - Environment matrix (Dev/UAT/QA/Prod)
   - Runbook template
4. Build docs via Docker (multi-stage: mkdocs build → nginx serve)
5. CI pipeline auto-builds docs site on push to /docs folder

Acceptance Criteria:
- Docs served on port 84 via Docker
- mkdocs.yml and all markdown files committed to Git
- Multi-stage Dockerfile builds and serves the docs
- 4 documentation pages created with real content

---

MORE ABOUT MKDOCS  

1. Live Reload Dev Mode

When writing documentation (editing the Markdown files), you need to see how their changes look in real-time. That's what dev mode does:

Student edits runbooks.md → saves file → browser auto-refreshes → sees updated page instantly

Without dev mode: Edit markdown → rebuild Docker image → restart container → refresh browser → check result. That's painful and slow.

With dev mode: MkDocs watches the files. The second you hit save, the browser updates automatically. It's the same concept as npm run dev for the React app — hot reload for docs.

In the docker-compose.yml, there are two services:

Service	Port	Purpose
docs-prod	84	Built static site served by Nginx (what users/team see)
docs-dev	8084	Live preview with auto-refresh (only used while writing docs)

Students use 8084 while writing, then build and deploy to 84 for production. It's a workflow thing — not two permanent servers.

2. Runbook Template

A runbook is an operational instruction manual — step-by-step procedures for when things happen in production. Think of it like a recipe book, but for servers.

Every real DevOps team has them. Eg When it's 2 AM and production is down, you don't want the on-call engineer guessing — you want them following a tested checklist.

Here's An Example of what the you would fill in as you complete the project:

RUNBOOK: Deploy New Version
═══════════════════════════
When to use:  New release ready for production
Who can run:  DevOps team lead

Steps:
  1. Verify build passed in Jenkins → check #healthpulse-builds Slack
  2. Confirm SonarQube quality gate passed
  3. Approve deployment in pipeline (manual gate)
  4. Monitor Datadog dashboard during rollout
  5. Verify /health endpoint returns 200
  6. If health check fails → pipeline auto-rolls back via Ansible

───────────────────────────

RUNBOOK: Rollback Production
════════════════════════════
When to use:  Production deployment caused errors
Who can run:  Any DevOps team member

Steps:
  1. Run: ./scripts/k8s-manage.sh rollback
     OR: Trigger Ansible Tower rollback job
  2. Verify previous version is serving traffic
  3. Check Datadog for error rate returning to normal
  4. Post incident summary in wiki

───────────────────────────

RUNBOOK: Scale Application
══════════════════════════
When to use:  High traffic / slow response times
Who can run:  Any DevOps team member

Steps:
  1. Check Datadog → confirm CPU/memory is the bottleneck
  2. Run: REPLICAS=6 ./scripts/k8s-manage.sh scale
  3. Monitor HPA: kubectl get hpa -n healthpulse-prod
  4. Scale back down after traffic normalizes