# GitHub Actions CI/CD Workflows

## 📋 Overview

This directory contains the CI/CD workflows for the GAMILIT platform, implemented during Sprint 2 - Day 5. These workflows automate testing, building, and deployment processes for both frontend and backend applications.

---

## 🔄 Available Workflows

### 1. Frontend CI (`frontend-ci.yml`)

**Triggers:**
- Push to `main` or `develop` branches
- Pull requests to `main` or `develop` branches
- Only when frontend code changes

**Jobs:**
1. **Lint & Code Quality** - ESLint validation
2. **TypeScript Type Check** - Type safety validation
3. **Unit Tests** - Vitest test execution + coverage
4. **Build** - Development and production builds
5. **E2E Tests** - Playwright test execution
6. **Security Audit** - npm audit for vulnerabilities
7. **CI Summary** - Overall status report

**Key Features:**
- ✅ Parallel job execution for speed
- ✅ Bundle size analysis
- ✅ Code coverage reports (Codecov)
- ✅ Playwright test reports
- ✅ Build artifacts uploaded (7-day retention)

**Estimated Runtime:** ~5-8 minutes

---

### 2. Backend CI (`backend-ci.yml`)

**Triggers:**
- Push to `main` or `develop` branches
- Pull requests to `main` or `develop` branches
- Only when backend/database code changes

**Jobs:**
1. **Lint & Code Quality** - ESLint validation
2. **TypeScript Type Check** - Compilation validation
3. **Unit Tests** - Jest test execution (with PostgreSQL)
4. **Build** - NestJS application build
5. **Database Schema Validation** - DDL script checks
6. **API Documentation Check** - Swagger status verification
7. **Security Audit** - npm audit
8. **Cache Performance** - Caching validation
9. **CI Summary** - Overall status report

**Key Features:**
- ✅ PostgreSQL 15 test database
- ✅ Database schema validation
- ✅ API documentation verification (97% coverage)
- ✅ Caching implementation checks
- ✅ Build artifacts uploaded (7-day retention)

**Estimated Runtime:** ~6-10 minutes

---

### 3. Deploy to Production (`deploy-production.yml`)

**Triggers:**
- **Automatic:** Push to `main` branch → deploys to Staging
- **Manual:** Workflow dispatch with environment selection
- **Tags:** Version tags (v*) → deploys to Production

**Jobs:**
1. **Pre-deployment Checks** - Sprint 2 optimization verification
2. **Build Frontend** - Production build
3. **Build Backend** - Production build
4. **Prepare Database Migration** - DDL scripts packaging
5. **Deploy to Staging** - Automatic staging deployment
6. **Deploy to Production** - Manual approval required
7. **Health Check** - Post-deployment validation
8. **Notification** - Deployment summary

**Key Features:**
- ✅ Sprint 2 optimization verification
- ✅ Staging environment auto-deployment
- ✅ Production requires manual approval
- ✅ Database migration scripts packaged
- ✅ Artifacts retained for 30 days
- ✅ Health checks after deployment

**Estimated Runtime:** ~8-12 minutes

**Environments:**
- **Staging:** `https://staging.gamilit.com`
- **Production:** `https://gamilit.com`

---

### 4. Validate Constants SSOT (`validate-constants.yml`)

**Purpose:** Ensures Single Source of Truth (SSOT) for constants

**Triggers:**
- Push to `main` or `develop` branches
- Pull requests to `main` or `develop` branches

**Validations:**
1. ENUMs synchronization (Backend ↔ Frontend)
2. No hardcoding violations
3. API contract consistency
4. Constants usage compliance

**Key Features:**
- ✅ Prevents constant duplication
- ✅ Enforces SSOT policy
- ✅ Validates enum synchronization
- ✅ Checks API contract alignment

**Estimated Runtime:** ~3-5 minutes

---

## 🚀 Quick Start

### Running Workflows Locally

#### Frontend CI Simulation:
```bash
cd apps/frontend

# Lint
npm run lint

# Type check
npm run type-check

# Unit tests
npm run test:run
npm run test:coverage

# Build
npm run build:prod

# E2E tests
npm run test:e2e
```

#### Backend CI Simulation:
```bash
cd apps/backend

# Lint
npm run lint

# Build
npm run build

# Unit tests (requires PostgreSQL)
npm test
npm run test:cov
```

---

## 📊 Workflow Status Badges

Add these badges to your README.md:

```markdown
![Frontend CI](https://github.com/YOUR_ORG/gamilit/workflows/Frontend%20CI/badge.svg)
![Backend CI](https://github.com/YOUR_ORG/gamilit/workflows/Backend%20CI/badge.svg)
![Deploy to Production](https://github.com/YOUR_ORG/gamilit/workflows/Deploy%20to%20Production/badge.svg)
```

---

## 🔧 Configuration

### Secrets Required

Configure these secrets in GitHub repository settings:

#### For All Workflows:
- `CODECOV_TOKEN` - Codecov integration (optional)

#### For Deployment (deploy-production.yml):
- `AWS_ACCESS_KEY_ID` - AWS credentials (if using AWS)
- `AWS_SECRET_ACCESS_KEY` - AWS secret
- `HEROKU_API_KEY` - Heroku deployment (if using Heroku)
- `VERCEL_TOKEN` - Vercel deployment (if using Vercel)
- `DATABASE_URL_STAGING` - Staging database connection
- `DATABASE_URL_PRODUCTION` - Production database connection

### Environment Variables

Configure these in GitHub Actions settings:

**Frontend:**
- `VITE_API_URL` - Backend API URL
- `VITE_ENV` - Environment (development/staging/production)

**Backend:**
- `DATABASE_URL` - PostgreSQL connection string
- `REDIS_URL` - Redis cache connection (for production)
- `JWT_SECRET` - JWT signing secret
- `NODE_ENV` - Node environment

---

## 📈 Sprint 2 Optimizations Included

All workflows validate and report on Sprint 2 improvements:

### Day 1: Code Quality & Linting
- ✅ ESLint strict mode enforcement
- ✅ 204 'any' types documented

### Day 2: Performance Optimization
- ✅ Bundle size reduced 44% (645KB → 364KB)
- ✅ Main gzipped reduced 48%
- ✅ 6 vendor chunks for better caching

### Day 3: E2E Testing & Backend Caching
- ✅ Backend caching: -87% to -94% DB load
- ✅ Playwright E2E: 40+ scenarios (12 active)
- ✅ Response time: 150-250ms → 5-15ms

### Day 4: Documentation & Type Safety
- ✅ API Documentation: 97% coverage
- ✅ TypeScript analysis: 1,368 errors documented
- ✅ Storybook: Basic setup complete

---

## 🎯 Continuous Integration Best Practices

### ✅ Implemented:

1. **Fast Feedback** - Parallel job execution
2. **Fail Fast** - Critical jobs block deployment
3. **Comprehensive Testing** - Unit, integration, E2E
4. **Security** - Automated vulnerability scanning
5. **Artifacts** - Build outputs preserved
6. **Notifications** - Job status summaries
7. **Environment Parity** - Same Node/PostgreSQL versions

### 🔄 Future Enhancements:

- [ ] Add Lighthouse performance testing
- [ ] Implement visual regression testing (Chromatic)
- [ ] Add load testing (k6 or Artillery)
- [ ] Set up automatic dependency updates (Dependabot)
- [ ] Add Slack/Discord notifications
- [ ] Implement blue-green deployments
- [ ] Add rollback automation

---

## 🐛 Troubleshooting

### Workflow Fails: "npm ci" Step

**Cause:** Package-lock.json out of sync

**Solution:**
```bash
rm package-lock.json node_modules -rf
npm install
git add package-lock.json
git commit -m "chore: update package-lock.json"
```

### Workflow Fails: TypeScript Errors

**Status:** Expected (1,368 errors documented in Day 4)

**Solution:** Workflows use `continue-on-error: true` for TypeScript checks until Phase 1-3 fixes are implemented (see TYPESCRIPT-TYPE-SAFETY-ANALYSIS-DAY4.md)

### Workflow Fails: E2E Tests

**Cause:** Missing test data

**Solution:** 28 tests are skipped pending test data setup (see PLAYWRIGHT-E2E-SETUP-DAY3.md)

### Deployment Fails: Environment Not Found

**Solution:** Create environments in GitHub:
1. Go to Settings → Environments
2. Create "staging" and "production" environments
3. Add protection rules (require approvals for production)

---

## 📚 Related Documentation

- **Sprint 2 Day 5 Report:** `SPRINT-2-DAY-5-FINAL-REPORT.md`
- **API Documentation:** `API-DOCUMENTATION-REPORT-DAY4.md`
- **TypeScript Analysis:** `TYPESCRIPT-TYPE-SAFETY-ANALYSIS-DAY4.md`
- **E2E Testing:** `PLAYWRIGHT-E2E-SETUP-DAY3.md`
- **Backend Caching:** `BACKEND-CACHING-IMPLEMENTATION-DAY3.md`
- **Performance Optimization:** `SPRINT-2-DAY-2-FINAL-REPORT.md`

---

## 🎓 Workflow Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                     CODE PUSH / PR                          │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ├──► Frontend CI
                       │    ├─ Lint
                       │    ├─ Type Check
                       │    ├─ Unit Tests
                       │    ├─ Build (dev + prod)
                       │    ├─ E2E Tests
                       │    └─ Security Audit
                       │
                       ├──► Backend CI
                       │    ├─ Lint
                       │    ├─ Type Check
                       │    ├─ Unit Tests
                       │    ├─ Build
                       │    ├─ Database Validation
                       │    ├─ API Docs Check
                       │    └─ Security Audit
                       │
                       └──► Validate Constants
                            ├─ ENUMs Sync Check
                            ├─ No Hardcoding
                            └─ API Contract
                                    │
                                    ▼
                          ┌─────────────────┐
                          │   ALL PASS?     │
                          └────────┬────────┘
                                   │
                        ┌──────────┴──────────┐
                        │                     │
                       YES                   NO
                        │                     │
                        ▼                     ▼
              ┌─────────────────┐   ┌─────────────────┐
              │ Deploy Staging  │   │  Block Merge    │
              │  (automatic)    │   │  Notify Team    │
              └────────┬────────┘   └─────────────────┘
                       │
                       ▼
              ┌─────────────────┐
              │  Health Check   │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │ Manual Approval │
              │  for Production │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │Deploy Production│
              │    (manual)     │
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │  Health Check   │
              └─────────────────┘
```

---

**Created:** November 9, 2025
**Sprint:** Sprint 2 - Day 5
**Status:** ✅ CI/CD Workflows Complete
**Next:** Production deployment setup