Task_Reporter/openspec/specs/frontend-core/spec.md

frontend-core Specification

Purpose

TBD - created by archiving change add-react-frontend. Update Purpose after archive.

Requirements

Requirement: User Authentication Interface

The frontend SHALL provide a login interface that authenticates users against the backend API and maintains session state.

Scenario: Successful login

• WHEN a user enters valid AD credentials and submits the login form
• THEN the system SHALL:
  • Send POST request to /api/auth/login
  • Store the returned token in localStorage
  • Redirect user to the room list page
  • Display the user's display name in the navigation

Scenario: Failed login with invalid credentials

• WHEN a user enters invalid credentials
• THEN the system SHALL:
  • Display error message "Invalid credentials"
  • Keep user on login page
  • Clear the password field

Scenario: Session persistence across page refresh

• WHEN a user refreshes the page while logged in
• THEN the system SHALL:
  • Retrieve token from localStorage
  • Validate session is still active
  • Restore user session without requiring re-login

Scenario: Logout

• WHEN a logged-in user clicks the logout button
• THEN the system SHALL:
  • Send POST request to /api/auth/logout
  • Clear token from localStorage
  • Redirect to login page

Requirement: Incident Room List

The frontend SHALL display a filterable, searchable list of incident rooms accessible to the current user.

Scenario: Display room list

• WHEN a logged-in user navigates to the room list page
• THEN the system SHALL:
  • Fetch rooms from GET /api/rooms
  • Display rooms as cards with title, status, severity, and timestamp
  • Show the user's role in each room
  • Order by last activity (most recent first)

Scenario: Filter rooms by status

• WHEN a user selects a status filter (Active, Resolved, Archived)
• THEN the system SHALL:
  • Update the room list to show only rooms matching the filter
  • Preserve other active filters

Scenario: Search rooms

• WHEN a user enters text in the search box
• THEN the system SHALL:
  • Filter rooms by title and description containing the search text
  • Update results in real-time (debounced)

Scenario: Create new room

• WHEN a user clicks "New Room" and fills the creation form
• THEN the system SHALL:
  • Display template selection if templates exist
  • Submit room creation to POST /api/rooms
  • Navigate to the new room on success
  • Show error message on failure

Requirement: Incident Room Detail View

The frontend SHALL display complete incident room information including metadata, members, and provide management controls for authorized users.

Scenario: View room details

• WHEN a user navigates to a room detail page
• THEN the system SHALL:
  • Fetch room details from GET /api/rooms/{room_id}
  • Display room title, status, severity, location, description
  • Show member list with roles
  • Display created timestamp and last activity

Scenario: Update room metadata (Owner/Editor)

• WHEN an owner or editor updates room fields (title, severity, description)
• THEN the system SHALL:
  • Submit changes to PATCH /api/rooms/{room_id}
  • Update the UI optimistically
  • Revert on failure with error message

Scenario: Change room status (Owner only)

• WHEN a room owner changes status to Resolved or Archived
• THEN the system SHALL:
  • Prompt for confirmation
  • Submit status change to backend
  • Update room header to reflect new status
  • Broadcast status change to connected members

Scenario: View room with insufficient permissions

• WHEN a user tries to access a room they are not a member of
• THEN the system SHALL:
  • Display "Access Denied" message
  • Provide option to request access or return to room list

Requirement: Real-time Chat Interface

The frontend SHALL provide a real-time chat interface using WebSocket connections for instant message delivery.

Scenario: Connect to room chat

• WHEN a user opens a room detail page
• THEN the system SHALL:
  • Establish WebSocket connection to /api/ws/{room_id}?token={token}
  • Load message history from REST API
  • Display connection status indicator
  • Subscribe to real-time message updates

Scenario: Send text message

• WHEN a user types a message and presses Enter or clicks Send
• THEN the system SHALL:
  • Send message via WebSocket
  • Display message immediately (optimistic update)
  • Show delivery confirmation when acknowledged
  • Show error indicator if delivery fails

Scenario: Receive message from other user

• WHEN another user sends a message to the room
• THEN the system SHALL:
  • Display the new message in the chat
  • Scroll to the new message if user is at bottom
  • Show notification badge if user has scrolled up

Scenario: Display typing indicator

• WHEN another user is typing
• THEN the system SHALL:
  • Show "{username} is typing..." indicator
  • Hide indicator after 3 seconds of inactivity

Scenario: Edit own message

• WHEN a user edits their own message within edit window
• THEN the system SHALL:
  • Display edit input pre-filled with original content
  • Submit edit via WebSocket
  • Update message with "edited" indicator

Scenario: Delete own message

• WHEN a user deletes their own message
• THEN the system SHALL:
  • Prompt for confirmation
  • Submit delete via WebSocket
  • Remove or mark message as deleted in UI

Scenario: WebSocket reconnection

• WHEN WebSocket connection is lost
• THEN the system SHALL:
  • Display "Reconnecting..." indicator
  • Attempt reconnection with exponential backoff
  • Restore connection and sync missed messages
  • Show error after max retry attempts

Requirement: File Upload and Management Interface

The frontend SHALL provide file upload capabilities with progress indication, preview for images, and file management controls.

Scenario: Upload file via button

• WHEN a user clicks the upload button and selects a file
• THEN the system SHALL:
  • Validate file type and size client-side
  • Display upload progress bar
  • Upload to POST /api/rooms/{room_id}/files
  • Show file in chat/file list on success
  • Display error message on failure

Scenario: Upload file via drag and drop

• WHEN a user drags a file into the chat area
• THEN the system SHALL:
  • Show drop zone indicator
  • Accept the file on drop
  • Proceed with upload as button upload

Scenario: Preview image file

• WHEN a user clicks on an uploaded image
• THEN the system SHALL:
  • Open image in a modal preview
  • Allow zoom and pan
  • Provide download button

Scenario: Download file

• WHEN a user clicks download on a file
• THEN the system SHALL:
  • Fetch presigned URL from GET /api/rooms/{room_id}/files/{file_id}
  • Trigger browser download with original filename

Scenario: Delete file (uploader or owner)

• WHEN file uploader or room owner clicks delete on a file
• THEN the system SHALL:
  • Prompt for confirmation
  • Submit delete to DELETE /api/rooms/{room_id}/files/{file_id}
  • Remove file from UI

Scenario: View file list

• WHEN a user opens the files panel in a room
• THEN the system SHALL:
  • Fetch files from GET /api/rooms/{room_id}/files
  • Display files with thumbnails for images
  • Show filename, size, uploader, and timestamp
  • Support filtering by file type

Requirement: Member Management Interface

The frontend SHALL provide member management controls for room owners and editors with appropriate role-based access.

Scenario: View member list

• WHEN a user views a room
• THEN the system SHALL:
  • Display all active members
  • Show each member's role (Owner, Editor, Viewer)
  • Indicate online status for connected members

Scenario: Add member (Owner/Editor)

• WHEN an owner or editor adds a new member
• THEN the system SHALL:
  • Display member search/input field
  • Allow role selection
  • Submit to POST /api/rooms/{room_id}/members
  • Update member list on success

Scenario: Change member role (Owner only)

• WHEN an owner changes another member's role
• THEN the system SHALL:
  • Display role selector
  • Submit to PATCH /api/rooms/{room_id}/members/{user_id}
  • Update member display on success

Scenario: Remove member (Owner/Editor)

• WHEN an owner or editor removes a member
• THEN the system SHALL:
  • Prompt for confirmation
  • Submit to DELETE /api/rooms/{room_id}/members/{user_id}
  • Remove member from list

Scenario: Transfer ownership (Owner only)

• WHEN a room owner transfers ownership to another member
• THEN the system SHALL:
  • Prompt for confirmation with warning
  • Submit to POST /api/rooms/{room_id}/transfer-ownership
  • Update roles in UI (current owner becomes Editor)

Requirement: Responsive Layout and Navigation

The frontend SHALL provide a responsive layout that works on desktop and tablet devices with intuitive navigation.

Scenario: Desktop layout

• WHEN viewed on desktop (>1024px)
• THEN the system SHALL:
  • Display sidebar navigation
  • Show room list and detail side-by-side when applicable
  • Display member panel as sidebar

Scenario: Tablet layout

• WHEN viewed on tablet (768px-1024px)
• THEN the system SHALL:
  • Collapse sidebar to icons or hamburger menu
  • Use full width for content areas
  • Stack panels vertically

Scenario: Navigation between pages

• WHEN a user navigates using browser back/forward
• THEN the system SHALL:
  • Maintain correct route state
  • Preserve scroll position where applicable
  • Not lose unsent message drafts

Scenario: Error handling

• WHEN an API request fails
• THEN the system SHALL:
  • Display user-friendly error message
  • Provide retry option where applicable
  • Log error details for debugging
  • Not crash or show blank screen