Skip to content

frontend-development.md

Latest commit

 

History

History
192 lines (164 loc) · 9.6 KB

frontend-development.md

File metadata and controls

192 lines (164 loc) · 9.6 KB

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