Skip to content

Latest commit

 

History

History
252 lines (196 loc) · 7.55 KB

README.md

File metadata and controls

252 lines (196 loc) · 7.55 KB

Forge Health Monitor UI

A React-based Forge application for monitoring external service health checks. This is the main user interface that runs within Atlassian Jira and provides a comprehensive dashboard for managing health check services.

Overview

This Forge application serves as the primary interface for the Health Monitor system, allowing users to:

  • View all registered health check services
  • Monitor real-time status of external services
  • Register new services through the custom backend
  • Track service availability and performance

Features

📊 Health Monitoring Dashboard

  • Real-time status display for all services
  • Automatic refresh every 30 seconds
  • Visual indicators for service health (ALIVE/DOWN)
  • Detailed service information and timestamps

🔧 Service Management

  • Add New Services: Register external health check endpoints
  • Real-time Updates: Live status updates from the backend
  • User Information: Display service ownership and details
  • Error Handling: Comprehensive error states and messages

🔐 Security & Compliance

  • Runs on Atlassian Policy: Fully compliant with Atlassian requirements
  • Cryptographic Signatures: Ed25519 signature verification for backend authentication
  • Tenant Isolation: Proper data separation per tenant
  • No Egress: All processing within Atlassian infrastructure

Installation & Build

Prerequisites

  • Node.js 22+
  • Forge CLI installed and configured
  • Access to Atlassian Cloud instance

Quick Setup

  1. Install Dependencies

    npm install

  2. Build for Production

    npm run build

  3. Start Development Server

    For local development with Forge tunnel access:

    npm run start

Development Workflow

  1. Start Development Server

    npm run start

  2. Start Forge Tunnel

    forge tunnel

  3. Access Application

    • Open the tunnel URL in your browser
    • Or access through your Jira instance

Project Structure

src/
├── components/         # React components
│   ├── Header.tsx     # Main header with actions
│   ├── RecordsList.tsx # Health check records list
│   ├── RecordCard.tsx # Individual service card
│   └── index.ts       # Component exports
├── hooks/             # Custom React hooks
│   ├── useRecords.ts  # Records management hook
│   └── index.ts       # Hook exports
├── utils/             # Utility functions
│   ├── registration.ts # Service registration logic
│   └── index.ts       # Utility exports
├── types.ts           # TypeScript definitions
├── constants.ts       # Styling and configuration
├── App.tsx           # Main application component
└── index.tsx         # Application entry point

Architecture

Component Hierarchy

App
├── Header
│   ├── Service Registration Button
│   ├── Refresh Button
│   └── Status Information
└── RecordsList
    └── RecordCard (for each service)
        ├── Service URL
        ├── User Information
        ├── Status Badge
        └── Timestamps

Data Flow

  1. Initialization: Load context and trigger URL from Forge
  2. Records Loading: Fetch health check records from Forge storage
  3. Auto-refresh: Update records every 30 seconds
  4. Service Registration: Redirect to custom backend for new services
  5. Status Updates: Display real-time health check results

Configuration

Forge Variables

The application requires the following Forge variables to be set:

# Set backend URL for service registration
forge variables set BACKEND_URL https://your-backend-service.com

Environment Configuration

  • Development: Uses Forge tunnel for local development
  • Production: Deployed to Atlassian Cloud
  • Backend Integration: Communicates with custom backend server

API Integration

Forge Resolvers

The application uses several Forge resolvers:

  • getTriggerUrlAndBackendUrl: Get trigger URL and backend URL
  • getRecords: Fetch all health check records
  • getSignature: Get cryptographic signature for registration

Backend Communication

  • Service Registration: Redirects to custom backend with signed state
  • Health Check Data: Receives updates via Forge triggers
  • State Management: Handles base64-encoded state data

Authentication Flow

  1. Signature Generation: Forge generates Ed25519 signature for UUID (30-minute validity)
  2. State Creation: Registration state includes signature and other required data
  3. Backend Validation: Backend verifies signature using stored public key
  4. Service Registration: Only valid signatures allow service registration
  5. Ongoing Updates: All subsequent requests are signed and verified

Styling & Design

Design System

  • Atlassian Design System: Consistent with Atlassian products
  • Color Palette: Professional blue and gray tones
  • Typography: Clear hierarchy and readability
  • Spacing: Consistent spacing scale

Responsive Design

  • Mobile-first: Optimized for all screen sizes
  • Touch-friendly: Large buttons and touch targets
  • Flexible Layout: Adapts to different viewport sizes

Development

Available Scripts

  • npm run start - Start development server
  • npm run build - Build for production
  • npm run dev - Development with hot reload

Code Quality

  • TypeScript: Full type safety
  • Component Architecture: Modular, reusable components
  • Custom Hooks: Encapsulated business logic
  • Error Handling: Comprehensive error states

Deployment

Forge Deployment

  1. Build Application

    npm run build

  2. Deploy to Forge

    forge deploy

  3. Install in Jira

    forge install

Production Considerations

  • Performance: Optimized bundle size and loading
  • Security: Secure communication with backend
  • Monitoring: Error tracking and logging
  • Updates: Automatic refresh and status updates

Security Features

Cryptographic Authentication

  • Ed25519 Signatures: Backend authentication using digital signatures
  • UUID-based Signatures: Forge generates and signs UUID for 30-minute validity
  • Public Key Verification: Backend validates signatures using stored public keys
  • Signature Lifecycle: 30-minute signature expiration for security

Data Protection

  • State Encryption: Registration state data is base64 encoded
  • Secure Communication: HTTPS-only communication
  • Input Validation: Client-side validation for all inputs
  • XSS Prevention: Proper data sanitization

Compliance

  • Runs on Atlassian: Fully compliant with Atlassian policies
  • No Data Egress: All processing within Atlassian infrastructure
  • Tenant Isolation: Proper data separation
  • Audit Trail: Comprehensive logging and monitoring

Troubleshooting

Common Issues

  1. Backend URL Not Configured

    • Set the BACKEND_URL Forge variable
    • Ensure the backend server is running and accessible

  2. Records Not Loading

    • Check Forge resolver implementation
    • Verify database connectivity
    • Check browser console for errors

  3. Service Registration Fails

    • Verify backend server is running
    • Check HTTPS configuration
    • Ensure proper tunnel setup

  4. Build Errors

    • Check Node.js version (requires 22+)
    • Clear node_modules and reinstall
    • Verify TypeScript configuration

License

MIT License - see LICENSE file for details.