AI Engineering People & Teams

AI Engineering modules and deployment for Org Pulse, an internal engineering dashboard connecting Jira, GitHub, and GitLab data with team rosters to surface delivery insights.

This repo contains AI Eng-specific modules, platform customizations, and deployment overlays. The core platform (@org-pulse/core) is installed as an npm dependency.

Quick Start (Demo Mode)

Run the app with sample data — no credentials needed:

npm install
npm run setup          # Symlinks core platform files into the workspace

echo "DEMO_MODE=true" > .env
echo "VITE_DEMO_MODE=true" >> .env

npm run dev:full

Open http://localhost:5173.

Quick Start (Full Setup)

For real Jira and GitHub data:

Prerequisites

• Node.js 22+
• Red Hat VPN (required for LDAP roster sync)
• @redhat.com Google account

1. Install dependencies

npm install
npm run setup          # Symlinks core platform files into the workspace

2. Configure environment

cp .env.example .env

Edit .env with your credentials:

# Required
JIRA_EMAIL=you@redhat.com
JIRA_TOKEN=your-jira-api-token        # From https://id.atlassian.com/manage-profile/security/api-tokens
ADMIN_EMAILS=you@redhat.com

# Optional — GitHub contribution stats
GITHUB_TOKEN=your-github-classic-pat   # Classic PAT with read:user scope

# Optional — automated roster sync from Google Sheets
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./secrets/google-sa-key.json

# Optional — Workflow Validation (backend only; read-only account)
WORKFLOW_VALIDATION_OPENSEARCH_URL=https://your-opensearch-api.example.com
WORKFLOW_VALIDATION_OPENSEARCH_USERNAME=your-read-only-username
WORKFLOW_VALIDATION_OPENSEARCH_PASSWORD=your-read-only-password

OpenSearch credentials are consumed only by the Express backend. The Vue app calls the module API and must never receive or query OpenSearch with them. An unauthenticated local POC remains available by setting only WORKFLOW_VALIDATION_OPENSEARCH_URL=http://localhost:9200.

Jira API Token: Go to https://id.atlassian.com/manage-profile/security/api-tokens, click "Create API token", and paste the value as JIRA_TOKEN.

GitHub Token: Create a classic Personal Access Token (not fine-grained — GraphQL API doesn't support those yet) at https://github.com/settings/tokens with the read:user scope.

Google Service Account (for roster sync): See Google Service Account Setup below.

3. Start dev servers

npm run dev:full

This starts both the Vite frontend (port 5173) and the Express backend (port 3001). Vite proxies /api requests to the backend.

• Frontend: http://localhost:5173
• API: http://localhost:3001/api

Product Builds channel data

Set PRODUCT_BUILDS_API_URL in .env, or the Product Builds API URL in Settings, to a dashboard service that exposes GET /channels and GET /channels/{name}. Restart the Express server after changing .env. The Channels view reads its catalog, package versions and base-image history through that service. A configured URL is used even when the rest of Org Pulse runs in demo mode. Only an unconfigured demo uses sample channels; failed dashboard requests remain errors.

The page labels dashboard data and its catalog update date. An empty build history and missing wheel classifications are displayed as supplied by the dashboard. The catalog update date does not guarantee every package index was refreshed successfully.

4. Configure roster sync (first run)

On first launch, a yellow banner will appear directing you to Settings. There you can configure:

• Org roots — LDAP UIDs of org leaders whose teams you want to track (e.g., shgriffi)
• Google Sheet ID — The spreadsheet ID from the Google Sheets URL (the long alphanumeric string). Sheet names are auto-discovered.

Click "Sync Now" to populate the roster. The app will also sync automatically once every 24 hours.

Google Service Account Setup

To use the Google Sheets roster sync:

1. Go to the Google Cloud Console
2. Create or select a project
3. Enable the Google Sheets API (APIs & Services > Library)
4. Create a Service Account (APIs & Services > Credentials > Create Credentials)
5. Create a JSON key for the service account and download it
6. Place the key file at secrets/google-sa-key.json (this path is gitignored)
7. Set GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./secrets/google-sa-key.json in .env
8. Share your Google Sheet with the service account email (the client_email in the JSON key)

Commands

npm run dev:full              # Start frontend + backend
npm run dev                   # Frontend only (Vite)
npm run dev:server            # Backend only (Express, needs .env)
npm test                      # Run all tests
npm run test:watch            # Tests in watch mode
npm run lint                  # ESLint
npm run build                 # Production build
npm run setup                   # Symlink core platform into workspace
npm run validate:modules      # Validate module manifests
npm run validate:openapi      # Validate OpenAPI annotations
npm run validate:dockerfile-deps  # Verify Dockerfile deps match package.json
npm run analyze:release-blockers  # Fetch, analyze, and upload blocker insights (CI secrets required)
npm run update:view-owners        # Regenerate platform/view-owners/owners.js from git history

# Container-based tests (requires Docker/Podman)
make smoke-test                 # Run smoke tests against AI Eng images
make test-module MODULE=<name>  # Run integration tests for a module

Tech Stack

• Frontend: Vue 3, Vite 8, Tailwind CSS 3, Chart.js 4
• Backend: Express (single server for local dev and production)
• Auth: OpenShift OAuth proxy (production), no auth (local dev)
• Storage: Local filesystem (./data/), PVC in OpenShift
• Hosting: OpenShift with ArgoCD
• Testing: Vitest (unit), Playwright (smoke & integration)

Deployment

Deployed to OpenShift via ArgoCD. AI Eng images extend core images from @org-pulse/core. See docs/DEPLOYMENT.md for the full deployment guide.

Contributing

See CONTRIBUTING.md for development workflow, project structure, and code style guidelines.

Architecture and deployment details are in .claude/CLAUDE.md — Claude Code reads this automatically.