Skip to content

React Frontend Development Rules

Architecture

  • React 19 with TypeScript
  • Functional components with hooks
  • Modern CSS with responsive design
  • Accessibility-first approach

Key Files

Coding Standards

  • Use TypeScript interfaces for all data models
  • Implement proper error handling and loading states
  • Use semantic HTML with proper accessibility attributes
  • Follow React best practices (hooks, functional components)
  • Use CSS classes for styling (no inline styles)
  • Implement responsive design for mobile compatibility

Component Structure

  • App: Root component with data fetching and error handling
  • JwstDataDashboard: Main dashboard with multiple view modes:
  • Grid view: Card-based display
  • List view: Compact table format
  • Grouped view: By data type
  • Lineage view: Tree hierarchy showing processing levels (L1→L2a→L2b→L3)
  • Tag filtering: Dedicated tag dropdown plus clickable tag pills on cards
  • FITS type badges: Visual indicators for image vs table files
  • Refresh Metadata button: Re-fetch MAST metadata for all imports
  • MastSearch: MAST portal integration with:
  • Search by target, coordinates, observation, or program
  • Bulk import with progress tracking
  • Byte-level progress display (speed, ETA, per-file status)
  • Resume capability for interrupted downloads
  • ImageViewer: FITS image viewer with:
  • Multiple color maps (grayscale, hot, cool, rainbow, viridis, plasma, magma, inferno)
  • Stretch controls (linear, log, sqrt, asinh, zscale) with histogram visualization
  • Zoom and pan controls
  • Pixel coordinate display with WCS conversion
  • PNG export with current visualization settings
  • Header metadata display in sidebar
  • Graceful handling of non-image FITS files
  • CompositeWizard: RGB composite workflow with:
  • Per-channel image assignment and independent stretch/levels/curve controls
  • WCS-aware channel alignment for accurate RGB registration
  • Live composite preview during channel tuning
  • Final export step with overall image-viewer-style stretch/levels controls applied post-stack
  • Types:
  • JwstDataModel, ImageMetadata, SensorMetadata, ProcessingResult
  • LineageResponse, LineageFileInfo
  • ProcessingLevels, ProcessingLevelLabels, ProcessingLevelColors
  • MastSearchResult, MastImportResponse, ImportJobStatus
  • FileProgressInfo, ResumableJobSummary, MetadataRefreshResponse
  • ImageMetadata now includes: wavelengthRange, calibrationLevel, proposalId, proposalPi, observationTitle
  • Utilities:
  • getFitsFileInfo(): Classify FITS files by suffix (image vs table)
  • isFitsViewable(): Check if FITS file is viewable
  • calculateZScale(): Optimal display limits for FITS data
  • getColorMap(): Color map lookup tables

API Integration

  • Backend API base URL: http://localhost:5001 (configured in config/api.ts)
  • Use service layer for all API calls (never use fetch directly in components)
  • Services provide:
  • Consistent error handling via ApiError class
  • Automatic JSON parsing and error extraction
  • TypeScript typing for request/response
  • Clean separation of concerns

Service Layer Usage

// Import services
import { jwstDataService, mastService, ApiError } from '../services';

// Fetch data
const data = await jwstDataService.getAll(includeArchived);

// Handle errors
try {
  await mastService.startImport({ obsId });
} catch (err) {
  if (ApiError.isApiError(err)) {
    console.error(`API Error ${err.status}: ${err.message}`);
  }
}

Available Services

jwstDataService: - getAll(includeArchived?) - Fetch all data records - upload(file, dataType, description?, tags?) - Upload a file - process(dataId, algorithm, parameters?) - Trigger processing - archive(dataId) / unarchive(dataId) - Archive operations - getDeletePreview(obsId) / deleteObservation(obsId) - Delete operations - scanAndImportMastFiles() - Bulk import from disk

mastService: - searchByTarget(params, signal?) - Search by target name - searchByCoordinates(params, signal?) - Search by RA/Dec - searchByObservation(params, signal?) - Search by obs ID - searchByProgram(params, signal?) - Search by program ID - startImport(params) - Start import job - getImportProgress(jobId) - Poll progress - cancelImport(jobId) - Cancel job - resumeImport(jobId) - Resume failed job - importFromExisting(obsId) - Import from downloaded files - refreshMetadataAll() - Refresh all MAST metadata

compositeService: - generateNChannelPreview(channels, size, overall?) - Generate N-channel composite preview - exportNChannelComposite(channels, format, quality, width, height, overall?) - Export N-channel composite - generateNChannelComposite(request) - Full N-channel composite generation

mosaicService: - generateMosaic(params) - Generate WCS-aligned mosaic - generateAndSaveMosaic(params) - Generate and save mosaic to library - exportMosaic(params) - Async mosaic export via job queue - saveMosaic(params) - Async save-to-library via job queue - getFootprint(dataIds) - Compute WCS footprint polygons

discoveryService: - getFeaturedTargets() - Get curated featured targets list - suggestRecipes(observations) - Get composite recipe suggestions

semanticSearchService: - search(query, topK?, minScore?) - Natural language search over FITS metadata - getIndexStatus() - Get semantic index health

analysisService: - getRegionStatistics(params) - Compute region statistics - detectSources(params) - Detect astronomical sources - getTableInfo(dataId) - Get FITS table HDU metadata - getTableData(params) - Get paginated table data - getSpectralData(dataId, hduIndex?) - Get spectral column arrays

authService: - login(username, password) - Login and get tokens - register(username, password) - Create account - refreshToken(refreshToken) - Refresh access token - logout() - Revoke refresh token

signalRService: - connect(accessToken) - Connect to job progress hub - subscribeToJob(jobId, callbacks) - Subscribe to job events - disconnect() - Disconnect from hub

UI/UX Guidelines

  • Current theme: "Sunset Galaxy" gradient background
  • Use consistent spacing and typography
  • Implement loading spinners for async operations
  • Provide clear error messages and retry options
  • Use status indicators for processing states
  • Implement search and filtering functionality

Accessibility

  • Use proper ARIA labels and roles
  • Implement keyboard navigation
  • Provide alt text for images
  • Use semantic HTML elements
  • Ensure sufficient color contrast