assignment submission: added the required resources as per assignment requirement

.github/ARCHITECTURE.md

@@ -0,0 +1,213 @@
+System Architecture Overview
+============================
+
+System Components
+=================
+
+**Application Tier**
+```
+   Frontend (Next.js)        Backend (FastAPI)
+   - JavaScript/React        - Python 3.12
+   - Port 3000              - Port 8000
+   - Static assets          - REST API
+   └─ E2E Tests            └─ Unit Tests (pytest)
+```
+
+**CI/CD Tier**
+```
+   GitHub Actions (CI)
+   - Trigger: Push to develop
+   - Environment: Python 3.12, Node 20
+   - Caching: Docker Buildx cache
+   └─ Outputs: Docker images to Docker Hub
+```
+
+**Registry**
+```
+   Docker Hub
+   - Backend image: pg-agi-backend:{sha|latest}
+   - Frontend image: pg-agi-frontend:{sha|latest}
+   └─ Access: DOCKERHUB_TOKEN required
+```
+
+**Infrastructure (Optional)**
+```
+   Cloud Deployment Options
+   - AWS ECS (template provided)
+   - Kubernetes (template provided)
+   - Terraform IaC (modules provided)
+```
+
+CI Pipeline Flow
+================
+
+**Detailed Pipeline Execution**
+
+```
+1. CODE PUSH TO DEVELOP BRANCH
+   ↓
+2. GITHUB ACTIONS TRIGGER
+   ├─ Checkout repository
+   ├─ Setup Python 3.12
+   ├─ Setup Node.js 20
+   └─ Configure Docker Buildx
+   ↓
+3. BACKEND TESTING
+   ├─ Install dependencies: pip install -r requirements.txt
+   ├─ Run tests: python -m pytest app/test_main.py
+   └─ Verify: All tests pass
+   ↓
+4. FRONTEND TESTING & LINTING
+   ├─ Install dependencies: npm ci
+   ├─ Run linter: npm run lint
+   ├─ Install Playwright: npx playwright install --with-deps
+   ├─ Run unit tests: npm test
+   ├─ Run E2E tests: npx playwright test
+   └─ Verify: All tests pass
+   ↓
+5. BUILD DOCKER IMAGES
+   ├─ Backend image
+   │  ├─ Tag: short-sha and latest
+   │  ├─ Dockerfile: multi-stage Python build
+   │  └─ Cache: Docker Buildx cache
+   ├─ Frontend image
+   │  ├─ Tag: short-sha and latest
+   │  ├─ Dockerfile: multi-stage Node.js build
+   │  └─ Cache: Docker Buildx cache
+   └─ Verify: Images built
+   ↓
+6. PUSH TO DOCKER HUB
+   ├─ Authenticate: DOCKERHUB_TOKEN
+   ├─ Backend: pg-agi-backend:{sha|latest}
+   ├─ Frontend: pg-agi-frontend:{sha|latest}
+   └─ Verify: Images in Docker Hub
+   ↓
+7. CI COMPLETE
+   ├─ Duration: 3-5 minutes
+   ├─ Status: Success/Failure
+   └─ Next: Monitor logs, verify images
+```
+
+Data Flow
+=========
+
+**Application Communication**
+```
+Browser (Frontend)  ──HTTP──>  API (Backend)
+     ↓                              ↓
+  Next.js port 3000           FastAPI port 8000
+  - Renders UI                - Handles requests
+  - Makes API calls           - Returns responses
+  - E2E tests verify          - Unit tests verify
+```
+
+**CI Artifact Flow**
+```
+Git Repository
+     ↓
+GitHub Actions (CI)
+     ↓
+Build & Test Pipeline
+     ↓
+Docker Images
+     ↓
+Docker Hub Registry
+     ↓
+(Ready for deployment)
+```
+
+Deployment Architecture
+=======================
+
+**Current Status**
+- CI enabled on `develop` branch
+- Deployment workflows disabled on `main` branch (by design)
+- Prevents accidental cloud deployments before credentials are configured
+
+**Deployment Options (Optional)**
+- AWS ECS: Template in `infra/aws-ecs-config.md`
+- Kubernetes: Template in `infra/k8s-deployment.md`
+- Terraform IaC: Modules in `infra/terraform/`
+
+**To Enable Deployment**
+1. Configure cloud provider credentials
+2. Rename `.disabled` to `.yml` in `.github/workflows/`
+3. Update deployment target references
+4. Commit and push to `main` branch
+
+Testing and Validation
+======================
+
+**Backend Validation**
+- Framework: pytest
+- Location: `backend/app/test_main.py`
+- Tests: API endpoints, health checks, business logic
+- Coverage: Verified in CI on each commit
+
+**Frontend Validation**
+- Linting: ESLint (npm run lint)
+- Unit tests: npm test
+- E2E tests: Playwright on `frontend/e2e/frontend.spec.ts`
+- Tests: Page rendering, API integration, user interactions
+- Coverage: Verified in CI on each commit
+
+**E2E Test Coverage**
+- Verifies backend availability
+- Validates frontend rendering
+- Confirms API communication
+- Tests basic user workflows
+
+Security Considerations
+=======================
+
+**Secrets Management**
+- `DOCKERHUB_TOKEN`: Never exposed in logs
+- Scoped to: Docker Hub image push only
+- Stored in: GitHub repository secrets
+- Accessed in: CI workflow only
+
+**Image Security**
+- Multi-stage builds: Reduces image size and attack surface
+- Docker Hub registry: Authentication required
+- Tags: Immutable SHA + latest
+
+**Workflow Security**
+- CI workflows: Run on trusted GitHub runners
+- No manual approvals needed (trusted develop branch)
+- Deployment disabled by default (prevents accidents)
+
+Performance Considerations
+==========================
+
+**Build Caching**
+- Docker Buildx: Layer caching
+- GitHub Actions: Dependency caching
+- First build: ~5 minutes
+- Subsequent builds: ~3 minutes (with warm cache)
+
+**Test Optimization**
+- Parallel: Backend and frontend tests
+- Selective: Only changed code affected
+- Playwright: Full browser automation for E2E
+
+Monitoring and Observability
+=============================
+
+**CI Monitoring**
+- GitHub Actions: View workflow runs in Actions tab
+- Duration: Track build times
+- Status: Pass/fail per stage
+- Logs: Step-by-step execution details
+
+**Application Health**
+- Backend: pytest validates endpoints
+- Frontend: Playwright E2E validates user experience
+- Integration: Tests confirm backend-frontend communication
+
+Next Steps
+==========
+
+1. Review [SECRETS.md](SECRETS.md) for credential setup
+2. Follow [../../SETUP-COMPLETE.md](../../SETUP-COMPLETE.md) for configuration
+3. Read [PIPELINE.md](PIPELINE.md) for detailed pipeline info
+4. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for issue resolution

.github/PIPELINE.md

@@ -0,0 +1,34 @@
+Pipeline Reference
+==================
+
+CI (develop)
+------------
+- Workflow: `.github/workflows/ci-develop.yml`
+- Stages: tests (backend pytest, frontend npm), Playwright E2E, build and push Docker images
+- Outputs: Docker Hub images `pg-agi-backend` and `pg-agi-frontend` tagged with short SHA and `latest`
+
+Deployment (main)
+-----------------
+- Workflows provided as `.disabled` templates: `deploy-main.yml.disabled`, `cd-main.yml.disabled`
+- Intended for enabling after credentials and targets are set
+- Supports adaptation for AWS ECS, GCP Cloud Run, or custom targets
+
+Secrets
+-------
+- `DOCKERHUB_TOKEN` (required)
+- `DOCKERHUB_USERNAME` (optional; defaults to repository owner)
+
+Caching and tagging
+-------------------
+- Uses Buildx with GitHub Actions cache
+- Tags: short Git SHA and `latest`
+
+Testing steps
+-------------
+- Backend: `python -m pytest app/test_main.py`
+- Frontend: `npm test` (placeholder), `npm run lint`, `npx playwright test`
+
+Notes for enabling deployment
+-----------------------------
+- Uncomment or rename the deployment workflows
+- Add cloud credentials and update registry references if not using Docker Hub

.github/QUICK-REFERENCE.md

@@ -0,0 +1,140 @@
+Quick Reference Guide
+=====================
+
+Git Branches
+============
+
+| Branch | Purpose | Trigger |
+|--------|---------|---------|
+| `develop` | CI pipeline | Any push |
+| `main` | Deployment templates | Disabled |
+
+GitHub Secrets
+==============
+
+**Required:**
+- `DOCKERHUB_TOKEN` - Docker Hub personal access token
+
+**Optional:**
+- `DOCKERHUB_USERNAME` - Docker Hub username (defaults to repo owner)
+
+**Where to add:**
+Settings > Secrets and variables > Actions > New repository secret
+
+Docker Image Tags
+=================
+
+**Format:**
+```
+<dockerhub-username>/<image-name>:<tag>
+```
+
+**Backend:**
+- Image: `pg-agi-backend`
+- Tags: `latest`, `{short-sha}`
+- Example: `myuser/pg-agi-backend:latest`, `myuser/pg-agi-backend:abc1234`
+
+**Frontend:**
+- Image: `pg-agi-frontend`
+- Tags: `latest`, `{short-sha}`
+- Example: `myuser/pg-agi-frontend:latest`, `myuser/pg-agi-frontend:abc1234`
+
+Common Commands
+===============
+
+**Backend (Local Testing)**
+```bash
+cd backend
+pip install -r requirements.txt
+python -m pytest app/test_main.py
+```
+
+**Frontend (Local Testing)**
+```bash
+cd frontend
+npm ci
+npm run lint
+npx playwright install --with-deps
+npx playwright test
+```
+
+**Docker Build (Backend)**
+```bash
+cd backend
+docker build -t pg-agi-backend:local .
+docker run -p 8000:8000 pg-agi-backend:local
+```
+
+**Docker Build (Frontend)**
+```bash
+cd frontend
+docker build -t pg-agi-frontend:local .
+docker run -p 3000:3000 pg-agi-frontend:local
+```
+
+**Push to develop (trigger CI)**
+```bash
+git push origin develop
+```
+
+CI Workflow Status
+==================
+
+**View in GitHub:**
+1. Navigate to Actions tab
+2. Click "CI (develop)" workflow
+3. View recent runs and status
+
+**Expected stages:**
+- Checkout & Setup
+- Backend Tests
+- Frontend Tests & Lint
+- Build Docker Images
+- Push to Docker Hub
+
+**Expected duration:** 3-5 minutes
+
+File Locations
+==============
+
+**Workflow files:**
+- CI: `.github/workflows/ci-develop.yml` (active)
+- Deployment: `.github/workflows/deploy-main.yml.disabled` (disabled)
+- Deployment: `.github/workflows/cd-main.yml.disabled` (disabled)
+
+**Application code:**
+- Backend: `backend/app/main.py`
+- Backend tests: `backend/app/test_main.py`
+- Frontend: `frontend/pages/index.js`
+- E2E tests: `frontend/e2e/frontend.spec.ts`
+
+**Dependencies:**
+- Backend: `backend/requirements.txt`
+- Frontend: `frontend/package.json`
+- Playwright: `frontend/playwright.package.json`
+
+Documentation Map
+=================
+
+**Getting started:**
+- [../../README.md](../../README.md)
+- [../../QUICKSTART.md](../../QUICKSTART.md)
+- [../../START-HERE.md](../../START-HERE.md)
+
+**Configuration:**
+- [../../SETUP-COMPLETE.md](../../SETUP-COMPLETE.md)
+- [SECRETS.md](SECRETS.md)
+
+**Reference:**
+- [PIPELINE.md](PIPELINE.md)
+- [WORKFLOW_REFERENCE.md](WORKFLOW_REFERENCE.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+
+Useful Links
+============
+
+- Docker Hub: https://hub.docker.com
+- GitHub Actions: Actions tab in repository
+- FastAPI docs: http://localhost:8000/docs (local)
+- Next.js app: http://localhost:3000 (local)