User Interface Documentation

Overview

The OCTAVIUS user interface is implemented as a React single-page application (SPA) following the Create React App standard structure. The application provides a responsive, interactive environment for survey data visualization and object classification.

Routing and Page Structure

All routes and page components are defined in ui/src/Routes/. The following routes constitute the primary user workflows:

Authentication Routes

  • login/ — User authentication endpoint; verifies credentials against the backend authentication service
  • logout/ — Session termination; destroys user session data and clears authentication tokens

Data Visualization and Interaction

  • contents/ — Home page; displays available organizations and their associated surveys as interactive cards
  • DynamicPage/ — Primary data viewing interface; renders survey data as customizable tables with dynamic columns derived from schema definitions
  • upload/ — Schema definition and import interface; enables administrators to upload CSV data and configure column definitions, data types, and image resources

User and Administrative Interfaces

  • profile/ — User account management; displays user profile information and account settings
  • userAdmin/ — User administration panel; restricted to administrators; provides functionality for user creation, modification, and deletion
  • orgAdmin/ — Organization administration panel; manages organizations, associated users, and survey page assignments
  • download/ — Data export interface; allows users to download classification results for a specific survey or data page

Legacy Routes

  • comcam/ — ComCam-specific survey interface; maintained for backward compatibility with legacy survey workflows

Component Architecture

Reusable Components

Common components are organized in ui/src/Components/:

  • header/ — Primary navigation header component; includes authentication state display and user menu
  • table/ — Generic data table component; powers the DynamicPage visualization with support for dynamic column rendering, sorting, and filtering
  • icons/ — Icon library; provides consistent iconography across the application
  • quote-display/ — Quote or notice display component; used for user messaging and notifications

Component Organization

Components follow a hierarchical structure aligned with routes. Page components are located in ui/src/Routes/, while shared utility components reside in ui/src/Components/.

API Integration

Method Organization

API helper functions are organized in ui/src/Methods/:

  • admin.js — Organization and survey query methods (create, read, update, delete operations)
  • users.js — User authentication and profile management (login, logout, profile retrieval)
  • classifications.js — Classification data retrieval and submission operations
  • sas.js — Security token (SAS) handling and generation for image access

Error Handling

Each method should implement appropriate error handling, including:

  • HTTP status code interpretation
  • User-facing error messaging
  • Fallback data when applicable
  • Logging for debugging purposes

Utilities and Helpers

Data Formatting

The ui/src/Utils/helpers/ directory contains utility functions for:

  • URL formatting and construction
  • Date/time formatting for display
  • Number and currency formatting
  • String manipulation and validation

Asynchronous Operations

The ui/src/Utils/async/ directory provides utilities for:

  • Data fetching and promise handling
  • Loading state management
  • Retry logic for failed requests
  • Request timeout handling

Environment Configuration

The API base URL is configured via the REACT_APP_API_URL environment variable. The default value is https://localhost:8443. This can be overridden during the build process or at runtime via environment configuration.

Development Best Practices

  • Use functional components with React hooks for state and lifecycle management
  • Implement proper error boundaries for improved error handling
  • Maintain separation between business logic (Methods) and presentation logic (Components)
  • Document non-obvious component behavior and configuration requirements
  • Use meaningful variable and function names for improved code readability
This site uses Just the Docs, a documentation theme for Jekyll.