docs(enrollment): expand README with setup, architecture, security, and troubleshooting

Author: NuwaniFonseka

README.md

@@ -2,35 +2,98 @@
 
 Enrollment Service is the course enrollment microservice in the University Student Management System (SE4010 Cloud Computing Assignment).
 
+## Table of Contents
+- [Features](#features)
+- [Service Purpose](#service-purpose)
+- [Architecture](#architecture)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [API Endpoints](#api-endpoints)
+- [Security Notes (Secret Manager + Snyk + JWT)](#security-notes-secret-manager--snyk--jwt)
+- [Inter-Service Communication Flow](#inter-service-communication-flow)
+- [Testing](#testing)
+- [Docker](#docker)
+- [CI/CD and Deployment Notes](#cicd-and-deployment-notes)
+- [Project Structure](#project-structure)
+- [Troubleshooting](#troubleshooting)
+- [Repository Artifacts Checklist](#repository-artifacts-checklist)
+
+## Features
+- JWT-protected write operations (`POST`, `PATCH`, `DELETE`) with fail-closed auth behavior.
+- Enrollment lifecycle management (create, list, check, update status, cancel).
+- Duplicate active enrollment prevention.
+- Inter-service validation with Student, Course, and Grade services.
+- MongoDB persistence via Mongoose.
+- Swagger/OpenAPI docs at `/api-docs`.
+- Security middleware stack: `helmet`, `cors`, rate limiter, and request logging.
+- Automated tests with Jest + Supertest.
+- Docker-ready deployment.
+
 ## Service Purpose
 - Enroll students into courses.
 - Track enrollment records and status.
 - Provide enrollment lookup endpoints for other services.
 - Integrate with Student Service and Course Service for validation.
-- Integrate with Grade Service to initialize grade records (when Grade Service is available).
+- Integrate with Grade Service to initialize grade records.
+
+## Architecture
+```text
+Client / API Gateway
+        |
+        v
+Enrollment Service (Express, Port 5003 local / 8080 Cloud Run)
+  - Auth middleware (JWT validation via Student Service)
+  - Enrollment routes/controllers
+  - Rate limiting + Helmet + CORS
+  - Swagger docs (/api-docs)
+        |
+        +--> MongoDB (enrollmentdb)
+        +--> Student Service (auth/validate + student checks)
+        +--> Course Service (course/capacity checks)
+        +--> Grade Service (initial grade creation)
+```
 
-## API Endpoints
-Base URL (Cloud Run): `https://enrollment-service-763150334229.us-central1.run.app`
+## Requirements
+- Node.js 18+ (recommended current LTS)
+- npm 9+
+- MongoDB (local or Atlas)
+- Docker (optional, for containerized run)
 
-- `POST /enroll` - Enroll a student in a course
-- `GET /enrollments` - Get all enrollments
-- `GET /enrollments/student/{studentId}` - Get enrollments by student
-- `GET /enrollments/course/{courseId}` - Get course roster
-- `GET /enrollments/check` - Check enrollment status
-- `PATCH /enrollments/{id}/status` - Update enrollment status
-- `DELETE /enroll/{id}` - Cancel enrollment
-- `GET /api-docs` - Swagger/OpenAPI UI
+## Quick Start
+### 1. Install dependencies
+```bash
+npm install
+```
+
+### 2. Configure environment
+```bash
+cp .env.example .env
+```
+Update `.env` values to your environment.
+
+### 3. Run the service
+```bash
+npm run dev
+```
 
-## Environment Variables
+### 4. Verify service
+- Health: `http://localhost:5003/`
+- API docs: `http://localhost:5003/api-docs`
+
+## Configuration
+### Environment Variables
 Required runtime variables:
 
-- `MONGO_URI` - MongoDB connection string (in Cloud Run, configured via Secret Manager)
-- `STUDENT_SERVICE_URL` - Base URL of Student Service
-- `COURSE_SERVICE_URL` - Base URL of Course Service
-- `GRADE_SERVICE_URL` - Base URL of Grade Service
-- `ALLOW_AUTH_BYPASS` - Optional local/dev switch (`true` only for controlled testing)
-- `ALLOW_MOCK_SERVICES` - Optional local/dev switch (`true` only for controlled testing)
-- `PORT` - Service port (Cloud Run uses `8080`)
+| Variable | Required | Description |
+|---|---|---|
+| `MONGO_URI` | Yes | MongoDB connection string (Cloud Run maps from Secret Manager) |
+| `STUDENT_SERVICE_URL` | Yes | Base URL of Student Service |
+| `COURSE_SERVICE_URL` | Yes | Base URL of Course Service |
+| `GRADE_SERVICE_URL` | Yes | Base URL of Grade Service |
+| `ALLOW_AUTH_BYPASS` | No | Local/dev auth bypass switch (`true` only for controlled testing) |
+| `ALLOW_MOCK_SERVICES` | No | Local/dev mock switch (`true` only for controlled testing) |
+| `PORT` | No | Service port (Cloud Run uses `8080`, local default in `.env.example` is `5003`) |
 
 ### Local `.env` example
 ```env
@@ -43,16 +106,64 @@ ALLOW_AUTH_BYPASS=false
 ALLOW_MOCK_SERVICES=false
 ```
 
-## Run Locally
+## API Endpoints
+Base URL (production): configured via deployment/environment
+
+Base URL (local): `http://localhost:5003`
+
+- `GET /` - Health check
+- `POST /enroll` - Enroll a student in a course (protected)
+- `GET /enrollments` - Get all enrollments (protected)
+- `GET /enrollments/student/{studentId}` - Get enrollments by student
+- `GET /enrollments/course/{courseId}` - Get course roster
+- `GET /enrollments/check` - Check enrollment status
+- `PATCH /enrollments/{id}/status` - Update enrollment status (protected)
+- `DELETE /enroll/{id}` - Cancel enrollment (protected)
+- `GET /api-docs` - Swagger/OpenAPI UI
+
+## Security Notes (Secret Manager + Snyk + JWT)
+- `MONGO_URI` is not deployed as plain text; it is mapped from Google Secret Manager.
+- CI includes Snyk security scanning before build/deploy.
+- API Gateway and service endpoints support JWT-based protected routes for authorized operations.
+- Enrollment auth is fail-closed by default: failed token validation returns `401` (no implicit production bypass).
+- Inter-service validation is fail-closed by default: unreachable dependencies return `503` (no implicit production mock success).
+- Input validation and duplicate enrollment checks are enforced in business logic.
+- Global rate limit is enabled with `express-rate-limit` (100 requests per 15-minute window per IP).
+
+## Inter-Service Communication Flow
+Enrollment Service communicates with other microservices:
+
+- Student Service:
+  - Validate student identity/existence before enrollment.
+- Course Service:
+  - Validate course and capacity before enrollment.
+- Grade Service:
+  - Create/initialize grade record after successful enrollment.
+
+Typical `POST /enroll` flow:
+1. Receive enrollment request (`student_id`, `course_id`).
+2. Validate auth token via Student Service (`/auth/validate`) for protected routes.
+3. Call Student Service validation endpoint.
+4. Call Course Service validation/capacity endpoint.
+5. Save enrollment record in Enrollment DB.
+6. Call Grade Service to create initial grade record (if configured/available).
+
+## Testing
+Run tests:
+```bash
+npm test
+```
+
+Run tests with coverage:
 ```bash
-npm install
-cp .env.example .env
-# update .env values
-npm run dev
+npm run test:coverage
 ```
 
-Local docs:
-- `http://localhost:5003/api-docs`
+Current test suite covers:
+- Health and docs endpoints.
+- Auth middleware behavior.
+- Enrollment create/list/check/update/cancel routes.
+- Basic security headers (Helmet) and CORS behavior.
 
 ## Docker
 Build and run:
@@ -71,7 +182,7 @@ GitHub Actions workflow file:
 Pipeline stages:
 1. Test
 2. Snyk Security Scan (fails on high/critical)
-3. Build and Push Docker image to Docker Hub
+3. Build and push Docker image to Docker Hub
 4. Deploy to Google Cloud Run
 
 Cloud deployment:
@@ -80,30 +191,45 @@ Cloud deployment:
 - Image: `docker.io/nuwanifonseka/enrollment-service:latest`
 - Secret mapping in deploy step: `MONGO_URI=MONGO_URI:latest`
 
-## Security Notes (Secret Manager + Snyk + JWT)
-- `MONGO_URI` is not deployed as plain text; it is mapped from Google Secret Manager.
-- CI includes Snyk security scanning before build/deploy.
-- API Gateway and service endpoints support JWT-based protected routes for authorized operations.
-- Enrollment auth is fail-closed by default: failed token validation returns `401` (no implicit production bypass).
-- Inter-service validation is fail-closed by default: unreachable dependencies return `503` (no implicit production mock success).
-- Input validation and duplicate enrollment checks are enforced in business logic.
+## Project Structure
+```text
+enrollment-service/
+|-- src/
+|   |-- controllers/
+|   |   `-- enrollmentController.js
+|   |-- middleware/
+|   |   `-- auth.js
+|   |-- models/
+|   |   `-- Enrollment.js
+|   |-- routes/
+|   |   `-- enrollmentRoutes.js
+|   |-- services/
+|   |   `-- externalServices.js
+|   |-- server.js
+|   `-- swagger.yaml
+|-- tests/
+|   `-- enrollment.test.js
+|-- .github/workflows/main.yml
+|-- Dockerfile
+|-- package.json
+`-- README.md
+```
 
-## Inter-Service Communication Flow
-Enrollment Service communicates with other microservices:
+## Troubleshooting
+### "MONGO_URI not defined in environment"
+Set `MONGO_URI` in `.env` or environment before starting the service.
 
-- Student Service:
-  - Validate student identity/existence before enrollment.
-- Course Service:
-  - Validate course and capacity before enrollment.
-- Grade Service:
-  - Create/initialize grade record after successful enrollment.
+### Token validation returns `401`
+Check:
+1. Authorization header is present as `Bearer <token>`.
+2. `STUDENT_SERVICE_URL` is reachable.
+3. `ALLOW_AUTH_BYPASS` is `false` in production.
 
-Typical `POST /enroll` flow:
-1. Receive enrollment request (`student_id`, `course_id`).
-2. Call Student Service validation endpoint.
-3. Call Course Service validation/capacity endpoint.
-4. Save enrollment record in Enrollment DB.
-5. Call Grade Service to create initial grade record (if configured/available).
+### Dependency services unavailable (`503`)
+Check Student/Course/Grade service URLs and network connectivity. In local controlled testing, use mock/bypass flags only when intentional.
+
+### Port conflict locally
+Change `PORT` in `.env` and restart the app.
 
 ## Repository Artifacts Checklist
 This repository includes: