stuartshay/otel-ui repository overview

⁠otel-ui

React frontend for the otel-demo⁠ API with OAuth2 authentication.

⁠Overview

A modern React + TypeScript frontend that consumes the otel-demo Flask API, featuring:

• OAuth2/PKCE Authentication - AWS Cognito integration
• Type-safe API Client - Uses @stuartshay/otel-types⁠
• Distributed Tracing - Displays trace IDs from API responses
• Responsive Design - Mobile-friendly UI
• Docker Deployment - nginx container for K8s

Deployment Status: Version 1.0.82 deployed to ui.lab.informationcart.com⁠ 🚀

Authentication: ✅ Fully functional OAuth2/PKCE flow with login, callback, and logout

⁠Quick Start

# Run setup script
./setup.sh

# Start development server
npm run dev

# Open http://localhost:5173

⁠Development

⁠Git Workflow

⚠️ CRITICAL: Never commit directly to main. All changes must go through pull requests.

• main - Production branch (protected, PR-only, direct commits forbidden)
• develop - Development branch (work here for regular changes)
• feature/ - Feature branches (use for isolated features)

Two workflow options:

Option 1 - Direct develop to main (for regular changes):

git checkout develop
git pull origin develop
# Make your changes
git add .
git commit -m "feat: description"
git push origin develop
# Create PR: develop → main on GitHub

Option 2 - Feature branch (for isolated features):

git checkout develop  # or main
git pull origin develop
git checkout -b feature/my-feature
# Make your changes
git add .
git commit -m "feat: description"
git push origin feature/my-feature
# Create PR: feature/my-feature → main on GitHub

Never do this:

git checkout main
git commit ...  # ❌ FORBIDDEN
git push origin main  # ❌ FORBIDDEN

⁠Prerequisites

• Node.js 24.x (recommend using nvm⁠)
• npm 11.x

⁠Environment Configuration

Production (.env):

• API: https://otel.lab.informationcart.com
• Auth: https://ui.lab.informationcart.com/callback
• Used for Docker builds

Development (.env.local):

• API: http://localhost:8080
• Auth: http://localhost:5173/callback
• Copy from .env.example and customize

⁠Commands

⁠Infrastructure

⁠Troubleshooting

⁠Local Development

Cannot connect to API:

• Ensure otel-demo is running: cd ../otel-demo && python run.py
• Check .env.local has VITE_API_BASE_URL=http://localhost:8080
• Verify CORS is enabled in otel-demo .env

Authentication issues:

• Clear localStorage: localStorage.clear() in browser console
• Hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
• Check Cognito redirect URI matches .env.local

Build errors:

# Clean and reinstall
rm -rf node_modules package-lock.json dist
npm install
npm run build

⁠Documentation

• Project Plan⁠ - Implementation roadmap
• Cleanup Guide⁠ - File organization
• Auth Debug Findings⁠ - OAuth troubleshooting
• Copilot Instructions⁠ - Development rules

⁠Related Repositories

• otel-demo⁠ - Flask API backend
• k8s-gitops⁠ - Kubernetes manifests
• @stuartshay/otel-types⁠ - TypeScript types

⁠License

MIT