Update project metadata and CI workflow

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+ "enabledPlugins": {
+ "mongodb@claude-plugins-official": true
+ }
+}

.devcontainer/README.md

@@ -0,0 +1,87 @@
+# Codespaces & Dev Container Setup
+
+This project is configured to work seamlessly in GitHub Codespaces or with VS Code Dev Containers.
+
+## Starting with Codespaces
+
+1. **Click "Code" → "Codespaces" → "Create codespace on main"** from the GitHub repo
+2. The devcontainer will automatically:
+ - Spin up a MongoDB instance (Atlas Local)
+ - Install all dependencies
+ - Seed sample data
+
+## Using with VS Code Dev Containers
+
+1. **Install the Dev Containers extension** in VS Code
+2. **Open the repo locally** and run: `Ctrl+Shift+P` → "Dev Containers: Reopen in Container"
+3. VS Code will build the environment and start MongoDB
+
+## Accessing Services
+
+Once the devcontainer is running:
+
+| Service | URL | Purpose |
+|---------|-----|---------|
+| React App | http://localhost:5173 | Frontend (Vite dev server) |
+| Express API | http://localhost:5050 | Backend REST API |
+| MongoDB | mongodb://admin:mongodb@localhost:27017 | Database (no browser UI) |
+| MongoDB VS Code Extension | N/A | Query database directly in VS Code |
+
+## Quick Start in Codespaces
+
+Once the devcontainer is fully loaded (wait for "Poststart" to complete):
+
+```bash
+# Terminal 1: Start the Express server
+cd mern/server
+npm start
+
+# Terminal 2: Start the React dev server
+cd mern/client
+npm run dev
+```
+
+Then open http://localhost:5173 in your browser.
+
+## Database Credentials
+
+- **Host**: `mongodb` (inside container) or `localhost:27017` (from host)
+- **Username**: `admin`
+- **Password**: `mongodb`
+- **Database**: `employees`
+
+## Seeding Sample Data
+
+The devcontainer automatically seeds sample data on startup. To manually reseed:
+
+```bash
+cd mern/server
+node seed.js
+```
+
+## VS Code Extensions
+
+The devcontainer includes these extensions:
+
+- **MongoDB for VS Code** — Query your MongoDB directly from VS Code
+- **TypeScript** — TypeScript language support
+- **Prettier** — Code formatter
+
+## Troubleshooting
+
+### MongoDB connection issues
+```bash
+# Check if MongoDB is running
+mongosh -u admin -p mongodb --eval "db.adminCommand('ping')"
+```
+
+### Port conflicts
+If ports 5050, 5173, or 27017 are already in use:
+- **Codespaces**: Automatic port forwarding handles this
+- **Local Dev Container**: Modify `docker-compose.yml` to use different ports
+
+### Rebuild the devcontainer
+```bash
+# VS Code: Ctrl+Shift+P → "Dev Containers: Rebuild Container"
+# CLI: devcontainer build --workspace-folder .
+```

.devcontainer/devcontainer.json

@@ -0,0 +1,48 @@
+{
+ "name": "MERN Stack with MongoDB",
+ "dockerComposeFile": "docker-compose.yml",
+ "service": "app",
+ "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+
+ "features": {
+ "ghcr.io/devcontainers/features/node:1": {
+ "version": "22"
+ }
+ },
+
+ "customizations": {
+ "vscode": {
+ "extensions": [
+ "mongodb.mongodb-vscode",
+ "ms-vscode.vscode-typescript-next",
+ "esbenp.prettier-vscode"
+ ],
+ "settings": {
+ "mongodb.connectionSslEnabled": false,
+ "mongodb.defaultAuthenticationDatabase": "admin"
+ }
+ }
+ },
+
+ "forwardPorts": [5050, 5173, 27017],
+ "portsAttributes": {
+ "5050": {
+ "label": "Express API",
+ "onAutoForward": "notify"
+ },
+ "5173": {
+ "label": "React Dev Server",
+ "onAutoForward": "notify"
+ },
+ "27017": {
+ "label": "MongoDB",
+ "onAutoForward": "silent"
+ }
+ },
+
+ "postCreateCommand": "cd mern/server && npm ci && node seed.js && cd ../client && npm ci",
+
+ "remoteEnv": {
+ "ATLAS_URI": "mongodb://admin:mongodb@mongodb:27017/employees"
+ }
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,34 @@
+version: '3.8'
+
+services:
+ app:
+ image: mcr.microsoft.com/devcontainers/javascript-node:22-bookworm
+ volumes:
+ - ../..:/workspaces:cached
+ command: sleep infinity
+ network_mode: service:mongodb
+ environment:
+ - ATLAS_URI=mongodb://admin:mongodb@mongodb:27017/employees
+ - PORT=5050
+
+ mongodb:
+ image: mongodb/mongodb-atlas-local:latest
+ restart: unless-stopped
+ ports:
+ - 27017:27017
+ environment:
+ MONGODB_INITDB_ROOT_USERNAME: admin
+ MONGODB_INITDB_ROOT_PASSWORD: mongodb
+ MONGO_INITDB_DATABASE: employees
+ volumes:
+ - mongodb-data:/data/db
+ - mongodb-config:/data/configdb
+ healthcheck:
+ test: mongosh --eval "db.adminCommand('ping')"
+ interval: 10s
+ timeout: 5s
+ retries: 5
+
+volumes:
+ mongodb-data:
+ mongodb-config:

.github/workflows/main.yaml

@@ -1,58 +1,71 @@
-# This is a basic workflow to help you get started with Actions
-
 name: CI
 
-# Controls when the workflow will run
 on:
- # Triggers the workflow on push or pull request events but only for the main branch
  push:
- branches: [ $default-branch ]
+ branches: [ main ]
  pull_request:
- branches: [ $default-branch ]
-
- # Allows you to run this workflow manually from the Actions tab
+ branches: [ main ]
  workflow_dispatch:
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
- # This workflow contains a single job called "build"
-
  build:
- # The type of runner that the job will run on
  runs-on: ubuntu-latest
  environment: Testing
  strategy:
  matrix:
- node-version: [14.x , 16.x]
- max-parallel: 1 
-
- # Steps represent a sequence of tasks that will be executed as part of the job
+ node-version: [20.x, 22.x]
+ max-parallel: 1
+ services:
+ mongodb:
+ image: mongo:latest
+ options: >-
+ --health-cmd mongosh
+ --health-interval 10s
+ --health-timeout 5s
+ --health-retries 5
+ ports:
+ - 27017:27017
+ env:
+ MONGO_INITDB_ROOT_USERNAME: admin
+ MONGO_INITDB_ROOT_PASSWORD: mongodb
+
  steps:
- # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- - uses: actions/checkout@v2
- with: 
- ref: 'main-test'
+ - uses: actions/checkout@v4
 
- - name: Install server npm packages
- uses: bahmutov/npm-install@v1
+ - name: Use Node.js ${{ matrix.node-version }}
+ uses: actions/setup-node@v4
  with:
- working-directory: mern/server
+ node-version: ${{ matrix.node-version }}
+ cache: 'npm'
+ cache-dependency-path: |
+ mern/server/package-lock.json
+ mern/client/package-lock.json
+
+ - name: Install server npm packages
+ run: npm ci
+ working-directory: mern/server
 
  - name: Install client npm packages
- uses: bahmutov/npm-install@v1
- with:
- working-directory: mern/client
+ run: npm ci
+ working-directory: mern/client
 
  - name: Start server in the background
- env: 
- ATLAS_URI: ${{ secrets.ATLAS_URI }}
- run: (cd mern/server && echo "ATLAS_URI=$ATLAS_URI" > config.env && npm start &)
+ env:
+ ATLAS_URI: mongodb://admin:mongodb@localhost:27017/
+ run: |
+ echo "ATLAS_URI=$ATLAS_URI" > config.env
+ npm start > /tmp/server.log 2>&1 &
+ echo "Server PID: $!"
+ working-directory: mern/server
 
- - name: Start React app in the background
- run: (cd mern/client && npm start &)
+ - name: Wait for server to be ready
+ run: |
+ npx wait-on http://localhost:5050/record --timeout 30000 || (cat /tmp/server.log && exit 1)
 
  - name: Install Cypress and run tests
- uses: cypress-io/github-action@v2
+ uses: cypress-io/github-action@v6
  with:
  working-directory: mern/client
+ start: npm run dev
+ wait-on: 'http://localhost:5173'
 

AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md — AI Agent Guide
+
+This file is the source of truth for AI agents working in this repository.
+
+## Project Overview
+
+Full-stack MERN CRUD app for managing employee records. React (Vite) frontend communicates with an Express REST API; MongoDB Atlas stores data in the `employees` database, `records` collection.
+
+## Project Structure
+
+```
+mern-stack-example/
+├── EDD.md # MongoDB data model — read before touching schema or routes
+├── mern/
+│ ├── client/ # React 18 + Vite + Tailwind CSS frontend
+│ │ ├── src/
+│ │ │ ├── App.jsx # Root component and routes
+│ │ │ ├── components/
+│ │ │ │ ├── Navbar.jsx
+│ │ │ │ ├── Record.jsx # Create / edit form
+│ │ │ │ └── RecordList.jsx # Main list view
+│ │ ├── vite.config.js
+│ │ └── package.json
+│ └── server/ # Node.js + Express REST API
+│ ├── db/
+│ │ └── connection.js # MongoDB Atlas connection (appName set here)
+│ ├── routes/
+│ │ └── record.js # GET / POST / PATCH / DELETE /record
+│ ├── seed.js # Database seed script
+│ ├── server.js # Express app entry point
+│ └── package.json
+└── .github/workflows/main.yaml # CI: install, start, Cypress e2e
+```
+
+## Build and Test Commands
+
+```bash
+# Install and start the API server
+cd mern/server
+npm install
+npm start # requires mern/server/config.env (see Environment Variables)
+
+# Install and start the React dev server
+cd mern/client
+npm install
+npm run dev # serves on http://localhost:5173
+
+# Seed the database
+cd mern/server
+node seed.js # requires ATLAS_URI in config.env
+
+# Run Cypress e2e tests (client must be running)
+cd mern/client
+npx cypress run
+```
+
+## Environment Variables
+
+Create `mern/server/config.env` (not committed):
+
+| Variable | Description | Example |
+|-------------|------------------------------------------|---------|
+| `ATLAS_URI` | MongoDB Atlas connection string | `mongodb+srv://user:pass@cluster.mongodb.net/` |
+| `PORT` | Port for the Express server | `5050` |
+
+## MongoDB Skills
+
+Use the official MongoDB agent skills from https://github.com/mongodb/agent-skills
+whenever the task is MongoDB-specific and a matching skill exists.
+
+## When To Use EDD.md
+
+Use [EDD.md](./EDD.md) as the source of truth for the MongoDB data model in this repository.
+
+Consult [EDD.md](./EDD.md) before making changes that touch:
+
+- MongoDB collections, document structure, or field names
+- Express routes that read or write database records
+- Validation, form fields, API payloads, or UI that depend on persisted data
+- Schema documentation, Mermaid diagrams, or entity modeling discussions