Issue Tracker Frontend

1. Introduction

The Issue Tracker module is a comprehensive system designed for reporting, tracking, managing, and resolving issues or tasks within the Nimbly application. It aims to streamline the workflow from issue identification to resolution, ensuring accountability and transparency across all operational facets. Strategically, the Issue Tracker is vital for maintaining application quality, improving user satisfaction by addressing concerns promptly, and providing valuable data for development planning and resource allocation. Efficient issue resolution directly impacts operational efficiency, reduces downtime or bug-related disruptions, and ultimately contributes to the overall reliability and professionalism of the Nimbly platform.

2. Overview

The Issue Tracker module provides a range of key functionalities to manage issues effectively:

Issue Creation: Allowing users to report new issues with detailed descriptions, attachments (screenshots, logs, etc.), and initial parameters like priority, department, affected version, and user-impact assessment.
Issue Assignment: Facilitating the assignment of issues to specific users, teams, or departments for action, ensuring clear ownership and responsibility.
Status Management: Enabling users to update the status of issues as they progress through different, often customizable, stages of a defined workflow (e.g., Open, Assigned, In Progress, Pending Review, Resolved, Closed, Reopened, Deferred).
Commenting and Collaboration: Providing a platform for users to add comments, share updates, attach relevant files, and collaborate on resolving issues. This includes features like @mentions to notify specific users.
Filtering and Searching: Offering robust filtering (by status, priority, assignee, reporter, creation/update date, custom fields, tags, etc.) and full-text search capabilities to quickly find specific issues or groups of issues.
Multiple Views: Presenting issues in different views such as a comprehensive list view (with customizable columns), a workflow-oriented Kanban view (with drag-and-drop functionality), and a detailed view for individual issues.
Notifications: Alerting users via email or in-app notifications about relevant issue activities, assignments, status changes, comments, and upcoming due dates.
Reporting and Analytics: Providing insights into issue trends, resolution times, team performance, common issue types, and backlog health through dashboards and exportable reports.

3. Purpose of this Document

This document provides a detailed technical understanding of the Issue Tracker module. It covers its architecture, core components, UI screens, API interactions, data flows, state management, key workflows, and dependent packages. The goal is to serve as a guide for developers, QA engineers, product managers, and other stakeholders who need to understand, maintain, or extend the module. It aims to be a living document, updated as the module evolves.

4. Screens and Routes

This section outlines the primary User Interface (UI) screens that constitute the Issue Tracker module. For each screen, the corresponding navigation route path, a direct link to its main page component in the GitHub repository, and a description of its purpose and key functionalities are provided.

Screen/Feature Name	Route Path	GitHub Link to Page Component	Description of Use and Key Functionalities
Issues List Page	`/issues`	src/pages/issues.js which loads IssuePage.tsx	This is the main landing page for the Issue Tracker module. It displays a comprehensive list of all issues. Users can typically switch between different views (e.g., Table, Kanban) using view tabs. Key actions include: creating a new issue (via a “New Issue” button), advanced filtering using a dedicated filter bar/panel (e.g., by status, priority, assignee, reporter, tags, custom fields), full-text searching, sorting by various columns (in Table view), and potentially bulk actions on selected issues (e.g., bulk edit status, assign to). The page displays key issue information in a summarized format, such as ID, title, status, priority, assignee, and last updated date. Pagination is employed for large datasets.
Issue Details Page	`/issues/:issueId`	src/pages/IssueDetails.js which loads IssueDetailsPage.tsx	This page provides an in-depth view of a single issue, identified by its unique `issueId` in the route. It presents all available information related to the issue, typically organized into sections: a main header with title, ID, status, and key actions (e.g., Edit, Change Status, Assign); a detailed description area; fields for priority, assignee, reporter, due date, creation date, last updated date; sections for attachments, comments/activity log, and potentially linked issues or subtasks. Users can update issue properties (if they have [permissions](../Settings/Access control/AccessControlOverview.md)), add comments, upload attachments, view change history, and collaborate with others. This screen is central to the detailed management and resolution of individual issues.

5. Core Components and Logic

This section delves into the internal architecture of the Issue Tracker module, detailing its primary components, controllers, state management strategies, and specialized views. It aims to provide a clear understanding of how these elements are organized and how they collaborate to deliver the comprehensive functionalities of the issue tracking system. The components are primarily located within the src/core/presentation/features/issueV2/ directory.

5.1 Component Structure Overview

The Issue Tracker’s frontend architecture within src/core/presentation/features/issueV2/ is modular, promoting separation of concerns and reusability. Key components are organized into specific subdirectories:

_components: Contains shared UI elements that are used across multiple parts of the Issue Tracker feature, such as specialized dropdowns, buttons, or layout elements.
_controller: Houses the business logic, view models, and controllers. These units orchestrate the data flow, handle user interactions, and manage the state logic, acting as an intermediary between the UI components and the underlying data services or state.
_states: Defines the state structures and potentially the state management logic (e.g., atoms, selectors if using Recoil, or similar constructs for other state management libraries) that are central to the feature’s dynamic behavior.
View-specific directories (e.g., tableView/, kanbanView/, detailsView/, listDetailsView/): These directories contain components and logic tailored to specific ways of presenting issue data. For example, tableView/ would handle the tabular display of issues, while kanbanView/ would manage the Kanban board interface.
createIssue/, bulkEdit/, issueApproval/: These directories likely encapsulate the UI and logic for specific complex features like creating new issues, performing bulk edits on multiple issues, and managing issue approval workflows.

graph TD
    A[Page Components:\nIssuePage.tsx, IssueDetailsPage.tsx] --> B[Controllers (_controller)]
    A --> C[View-Specific Components]
    C --> D[Shared UI Components (_components)]
    C --> B
    B --> E[State Management (_states)]
    F[Data Services / API Layer] --> B

    subgraph issueV2 Feature Structure
        A
        B
        C
        D
        E
    end

     If applicable
    F --> H((Backend APIs))

The diagram above illustrates the high-level interaction between the main parts of the Issue Tracker module. Page components serve as entry points, utilizing controllers for logic and data. View-specific components render the different UI representations (list, Kanban, details) and also use controllers. Shared UI components provide common visual elements. Controllers manage interactions with the state and data services, which in turn communicate with backend APIs and potentially a global application state.

Shared UI Components (`_components`)

Purpose: This directory is dedicated to housing a collection of reusable UI elements tailored for the Issue Tracker module. These components are designed to be versatile and are utilized across various views and sub-features within the issue tracking system, ensuring a consistent user experience and reducing code duplication.
Key Subdirectories and Examples:
- header/: Contains components related to page titles, section headers, and potentially action buttons or navigation elements that appear at the top of different issue views (e.g., IssuesHeader.tsx, IssueDetailsHeader.tsx).
- issueDetail/: This likely holds components used in the Issue Details view for displaying or editing specific fields of an issue.
  - AssignedUserSelect.tsx: A specialized dropdown for selecting and displaying the assigned user. It might fetch a list of users, allow searching, and display user avatars and names. Props could include currentUserId, onUserSelect, disabled.
  - PrioritySelect.tsx: A dropdown or set of buttons for selecting an issue’s priority. It would display priority icons/colors. Props: currentPriorityId, onPriorityChange.
  - DueDateSelect.tsx: A date picker component tailored for setting or displaying an issue’s due date. Props: currentDueDate, onDueDateChange.
  - FileViewer.tsx: A component used to display previews or links for attached files. It might handle different file types (images, PDFs, text files) and offer download capabilities. Props: fileObject, onDeleteFile.
- layout/: Provides structural components that define the overall layout of different parts of the Issue Tracker interface, such as IssueLayout.tsx, which might define the common page structure for issue-related screens.
- toolbar/: Includes components for constructing toolbars, which typically contain filtering options, search inputs, view switchers, and action buttons (e.g., IssueFilter.tsx, IssueSearchInput.tsx, ViewTabsTriggers.tsx).
Benefits: Using these shared components promotes consistency in UI and UX, makes development more efficient by reusing code, and simplifies maintenance as updates to a shared component are reflected everywhere it’s used. For instance, a shared StatusBadge.tsx component would ensure that issue statuses are displayed uniformly across lists, detail views, and Kanban boards.

Controllers and Business Logic (`_controller`)

Purpose: This is the brain of the Issue Tracker module from a frontend perspective. It contains the business logic, data orchestration, and state manipulation logic that drives the user interface. Controllers act as an intermediary layer between the visual components (views) and the data sources (state management, API services).
Key Subdirectories and Examples:
- createIssue/: Manages the complex process of creating new issues.
  - createIssueController.ts, createGenericIssueController.ts: These controllers would expose functions like handleCreateIssue(formData), validateField(fieldName, value). They handle user input events from the creation form, aggregate data, perform client-side validation (e.g., checking for required fields, data formats), interact with API services to submit the new issue, and update relevant state (e.g., loading status, success/error messages).
- issueDetails/: Contains controllers specific to the functionality of the Issue Details page.
  - issueDetailsController.tsx: Might expose functions like fetchIssueDetails(issueId), handleUpdateField(fieldName, newValue), addComment(commentText). It orchestrates fetching the full data for a specific issue, handles user attempts to edit fields (delegating to more specific controllers like issueStatusController if needed), manages comment submission, and coordinates updates to the issueDetails state. It transforms raw API data into a view-model suitable for the IssueDetailsPage.
  - issueStatusController.tsx: Focuses on status change logic, potentially handling workflows or permissions related to status transitions.
  - issueCommentTranslationController.tsx: Manages fetching, displaying, and potentially translating comments.
- issueKanban/: Holds logic for the Kanban board view.
  - IssueListKanbanController.tsx: Exposes functions like fetchKanbanData(filters), handleIssueDragEnd(issueId, newStatusId, oldStatusId, newIndex, oldIndex). It fetches issues grouped by status for the Kanban columns, manages state changes resulting from drag-and-drop operations (including optimistic updates and API calls to persist changes), and handles pagination or lazy loading within columns.
  - issueKanbanStatusController.tsx: Might deal with specific interactions related to Kanban statuses, like WIP limits or column configurations.
- issueListFilterController.tsx: Responsible for managing the state and logic of filtering options applied to the main issues list. It would expose functions like applyFilter(filterName, value), clearFilters(), setSearchQuery(query). It translates user selections in the filter UI into parameters for API requests and updates the relevant filter state.
- issueBulkEditController.tsx: Manages the functionality for selecting multiple issues and applying changes to them simultaneously.
- issueApprovalController.tsx: Handles logic related to issue approval workflows.
Role in Architecture: Controllers are crucial for separating concerns, keeping UI components lean and focused on presentation, while complex logic is encapsulated and managed centrally. They often interact heavily with state management systems and API abstraction layers.

State Management (`_states`)

Purpose: This directory is responsible for defining the structure, initial values, and potentially the access/update mechanisms for the various pieces of client-side state that the Issue Tracker module relies on.
Key Files and Examples:
- createIssueState.ts:
  - newIssueForm: Object holding form data (title, description, priorityId, assignedUserId, departmentId, customFieldValues, temporaryAttachmentIds).
  - isSubmitting: Boolean indicating API call in progress.
  - submissionError: String or object for API error messages.
  - validationStatus: Object mapping field names to validation error messages or boolean status.
  - availablePriorities, availableUsers, availableDepartments: Arrays to populate dropdowns, potentially fetched once.
- issueBulkEditState.ts:
  - selectedIssueIds: Array of issue IDs.
  - bulkEditChanges: Object with fields to update (e.g., { statusId: '...', priorityId: '...' }).
  - isApplyingBulkEdit: Boolean.
  - bulkEditProgress: Number (0-100) if edits are applied sequentially or in batches.
  - bulkEditErrors: Array of objects, each indicating an error for a specific issue ID during bulk update.
- issueDetails.ts:
  - currentIssueData: Object for the currently viewed issue (id, title, description, status, priority, comments, attachments, history).
  - isLoadingDetails: Boolean.
  - isEditing: Boolean or string indicating which field/section is being edited.
  - activeTab: String, e.g., ‘comments’, ‘history’, ‘attachments’.
  - commentInput: String for the new comment being typed.
- issueKanban.ts:
  - kanbanColumns: Array of objects: { id: 'statusId', title: 'Status Name', issues: [issueCardData], pageInfo: { currentPage: 1, hasMore: true } }.
  - isLoadingKanbanData: Boolean.
  - draggedIssueInfo: { issueId: '...', originalColumnId: '...', currentColumnId: '...' }.
  - appliedFilters: Object representing current filters affecting the Kanban board.
- issueSelectedItemState.ts:
  - selectedItems: Array of issue IDs, or a single issue ID, depending on whether multi-select is active. Used by context menus, toolbars, or master-detail views.
- resolveIssue.ts:
  - isResolving: Boolean.
  - resolveError: String.
  - issueToResolveId: String.
Approach: While the specific state management library isn’t explicitly detailed here, these files typically export state units that components and controllers can subscribe to.

View-Specific Components and Logic

The Issue Tracker module offers several distinct views to cater to different user workflows and preferences for managing issues. Each view is encapsulated within its own directory, containing the components, styling, and specialized logic required for its unique presentation and functionality. These views leverage the shared components, controllers, and state management systems described earlier to maintain consistency and data integrity.

A note on “List View” vs. “Table View”: The term ‘List View’ might sometimes refer to a simplified or more compact version of the Table View, perhaps with fewer columns displayed by default, a more mobile-friendly row layout, or focusing on a sequential stream of issues rather than a grid. If it’s a distinct view type not covered by tableView or listDetailsView (which itself contains a list component), it would prioritize quick scannability of key issue information, potentially with different interaction patterns than a dense data table. However, in many modern applications, ‘Table View’ often fulfills the traditional list requirements with enhanced features like column customization and sorting, making a separate, simpler ‘List View’ less common unless specific UI/UX goals dictate it. For the purpose of this document, the tableView is considered the primary component for presenting issues in a row-column format, and the listDetailsView incorporates a list component for its master pane.

Details View (`detailsView` and `IssueDetailsPage.tsx`)

Purpose: The Issue Details view (often encapsulated in IssueDetailsPage.tsx and utilizing components from detailsView/ and _components/issueDetail/) provides a comprehensive and interactive display of all information related to a single issue. It’s the central hub for understanding, discussing, and managing an individual issue’s lifecycle.
I. Overall Issue Details Page Structure:
- Layout Overview: The Issue Details view is typically organized into several logical sections to present comprehensive information without overwhelming the user. This often includes:
  - Header: Displaying the issue ID (e.g., “ISS-123”), its full title, and primary action buttons (e.g., “Edit”, “Change Status”, “Watch/Unwatch”, an “Actions” dropdown menu for less frequent operations like “Clone Issue”, “Delete Issue”).
  - Core Properties Panel: A section, often a sidebar or a prominent top block, showing key fields like Status (e.g., as a badge), Priority (e.g., with an icon), Assignee(s), Reporter, Due Date, Creation Date, Last Updated Date, and any parent/linked issues. These are often quick-glance items.
  - Description Section: The main body of the issue, detailing the problem, task, or feature request. This content is often rich text.
  - Attachments Section: Lists all files attached to the issue, with options to upload new ones.
  - Comments/Activity Section: A chronological or threaded view of all user comments and system-generated activity logs (e.g., status changes, assignee updates).
  - Custom Fields Section (if applicable): Displaying any additional custom data fields relevant to the issue type, organized logically.
- Dynamic Loading: Components like comments or large activity logs might be paginated or lazy-loaded (infinite scroll) to improve initial page load performance and reduce data overhead. The issueDetailsController.tsx would manage fetching these on demand.
II. Display and Editing of Core Properties:
- Fields are typically displayed in a read-only format by default, with clear visual cues (e.g., an “Edit” button or pencil icons next to fields) indicating editability based on user permissions.
  - Title/Summary:
    - Display: Prominently displayed at the top, often as a large heading. It should be clear and concise.
    - Edit UI: Clicking the title or an adjacent edit icon might convert the text into an input field. Changes are typically saved via an API call like PATCH /api/v2/issues/:issueId with a payload { title: 'new title' }. This interaction might be handled by issueDetailsController.tsx.
  - Description:
    - Display: Rendered as formatted text (e.g., supporting Markdown or HTML generated by a rich text editor during creation/editing). This ensures readability of potentially long and complex descriptions.
    - Edit UI: An “Edit Description” button or clicking into the description area (if permissions allow) would toggle a rich text editor (WYSIWYG, e.g., based on Draft.js or Slate.js). This allows for formatting, lists, links, and potentially inline images. Saved via API PATCH /api/v2/issues/:issueId with payload { description: 'new description content' }.
  - Status:
    - Display: Shown as a badge or pill with color-coding corresponding to the status (e.g., Blue for ‘Open’, Yellow for ‘In Progress’, Green for ‘Resolved’, Grey for ‘Closed’).
    - Edit UI: Typically a dropdown list showing available statuses based on the current issue status and defined workflow transitions (e.g., an ‘Open’ issue might only transition to ‘Assigned’ or ‘In Progress’). Selection triggers an API call: PATCH /api/v2/issues/:issueId (payload: { status_id: 'new_status_uuid' }). This logic is often managed by issueStatusController.tsx.
  - Priority:
    - Display: Often shown with an icon (e.g., upward arrow for High, downward for Low) and text (e.g., “Highest”, “Medium”).
    - Edit UI: A dropdown list of predefined priority levels. Changes call PATCH /api/v2/issues/:issueId (payload: { priority_id: 'priority_uuid' }). Managed by issuePriorityController.tsx.
  - Assignee(s) / Reporter:
    - Display: User avatar(s) and full name(s). Clicking a name might show a user profile popover.
    - Edit UI (for Assignee): A searchable user dropdown or a modal user picker, allowing one or more users to be assigned. Changes call PATCH /api/v2/issues/:issueId (payload: { assignee_ids: ['user_uuid1', 'user_uuid2'] }). Managed by issueUserController.tsx. The Reporter field is typically set at creation and is read-only thereafter.
  - Due Date / Start Date / End Date:
    - Display: Formatted date (e.g., “Jan 15, 2024”, “Next Monday”). May also show relative time (e.g., “in 3 days”, “overdue by 5 days”).
    - Edit UI: A date picker component (calendar view). Changes call PATCH /api/v2/issues/:issueId (payload: { due_date: 'YYYY-MM-DDTHH:mm:ssZ' }). Specialized controllers like issueDueDateController.tsx might handle this.
  - Custom Fields:
    - Display & Edit UI: Presentation and editing controls vary based on the custom field’s data type:
      - Text: Plain text display, text input for editing.
      - Number: Numeric display, number input for editing.
      - Dropdown: Selected option display, dropdown list for editing.
      - Date: Formatted date display, date picker for editing.
      - User Picker: Similar to Assignee display/edit. API calls would target specific custom field identifiers, possibly in a structured payload like { custom_fields: { 'field_uuid_1': 'new value', 'field_uuid_2': 'date_value' } }.
- Save Mechanism for Updates: Updates to fields can be saved individually (e.g., ‘on-blur’ or after a small debounce for text inputs, immediately for dropdowns) or grouped under a main ‘Save Changes’ button if the page enters a distinct ‘Edit Mode’. Optimistic UI updates are often used to make the interface feel responsive, with clear error handling if a save fails.
III. Comments Section (managed by issueActivity/IssueActivity.tsx or similar):
- Display:
  - Order: Comments are typically displayed chronologically; newest comments appearing either first (descending) or last (ascending) based on user/system preference, with descending being a common default for better visibility of recent activity.
  - Threading: Support for threaded comments allows replies to be nested under parent comments, visually indenting them to make discussions easier to follow and contextualize.
  - Author & Timestamp: Each comment clearly shows the author’s name (and often their avatar) and the timestamp of when it was posted (e.g., “Jane Doe - 2 hours ago” or “John Smith - Jan 10, 2024 at 3:45 PM”).
- Adding New Comments:
  - Input Area: A rich text editor is often provided for composing comments, allowing for formatting (bold, italics, lists, code blocks, blockquotes, inline images/links) and potentially @mentions (e.g., @username) to notify specific users about the comment.
  - Submission: A ‘Submit Comment’ or ‘Post’ button posts the comment content. This triggers an API call (e.g., POST /api/v2/issues/:issueId/comments with payload { text: 'comment content in markdown/html' }). Upon successful submission, the new comment is typically appended to the list in real-time or with a quick UI update, often with a highlight or animation.
- Editing and Deleting Comments:
  - [Permissions](../Settings/Access control/AccessControlOverview.md): Users might be able to edit or delete their own comments, often within a specific time window (e.g., 15 minutes after posting) or indefinitely, depending on system policy. Administrators or users with specific roles might have broader permissions to edit/delete any comment.
  - UI: Edit and Delete options typically appear on hover over a comment or via a context menu (’…’) on the comment. Editing would re-open the comment in an editor, while deleting would prompt for confirmation. API calls: PUT /api/v2/comments/:commentId (payload: { text: 'updated content' }) or DELETE /api/v2/comments/:commentId.
- System Activity: This section often interleaves system-generated activity logs alongside user comments. These logs provide an audit trail of changes to the issue, such as: ‘User X changed status from Open to In Progress’, ‘User Y updated Priority to High’, ‘User Z added attachment file_name.pdf’, ‘User A assigned this issue to User B’. These entries are typically styled differently from user comments for clarity.
IV. Attachments Section (logic might draw from createIssue/_components/attachmentForm/ but adapted for display and management within the details view; potentially managed by an issueAttachmentController.tsx):
- Upload Process:
  - UI: A dedicated area or button (e.g., “Add Attachment”) allows users to attach files. This often includes a drag-and-drop zone for convenience and a traditional ‘Browse Files’ button that opens the system file picker.
  - Multiple Files: Support for uploading multiple files simultaneously is common, with progress indicators for each file.
  - Limits & Types: Restrictions on file size (e.g., max 10MB per file) and allowed file types (e.g., images like JPEG, PNG, GIF; documents like PDF, DOCX, XLSX; log files like .txt, .log) are usually enforced client-side and validated server-side.
  - API: Files are uploaded via POST /api/v2/issues/:issueId/attachments or a more general /api/v2/attachments endpoint, which might then return attachment IDs to be associated with the issue in a subsequent API call.
- Display of Attachments:
  - List Format: Attachments are typically listed with their filename (often a clickable link), file size (e.g., “2.5 MB”), uploader’s name, and the date/time of upload.
  - Previews: Inline previews might be available for common image types (JPEG, PNG, GIF). For other types like PDFs or videos, a thumbnail or icon representing the file type is shown. Clicking an image preview might open it in a lightbox/modal for a larger view. Clicking non-image files may trigger a download or attempt to open in a new browser tab.
  - Download: Each attachment has a clear download link/button.
- Management:
  - Deleting Attachments: Users with appropriate permissions (usually the uploader of the specific attachment or an administrator/project manager) can delete attachments. This action typically requires confirmation. Deletion triggers an API call like DELETE /api/v2/attachments/:attachmentId.
  - Versioning (Advanced): While less common for basic issue trackers, some systems might support attachment versioning, where uploading a file with the same name can either replace the existing one or create a new version, with access to previous versions.

These detailed sections ensure that all aspects of an issue are clearly presented and manageable, facilitating effective communication and resolution. The specific components like AssignedUserSelect.tsx (from _components/issueDetail/) would be used within these sections for their respective functionalities.

List-Details View (`listDetailsView`)

Purpose: This directory appears to implement a common and powerful UI pattern: a master-detail view. It typically presents a list of issues (master) on one part of the screen, and when an issue is selected from the list, its full details (detail) are displayed in another part of the screen. This allows for quick navigation through issues while simultaneously viewing comprehensive information for the selected one. The “list” part of this view might be a simplified table or a custom list component.
Key Sub-Components & Functionality:
- DetailsView.tsx (within listDetailsView): This is likely the main orchestrator for this combined view.
- _components/issueList/: Contains components for rendering the list of issues (e.g., IssueList.tsx, IssueListItem.tsx). This list would allow selection of an issue to be displayed in the detail pane. It might include features like infinite scrolling or pagination.
- issueDetails/ (within listDetailsView): Manages the presentation of the selected issue’s details (e.g., IssueDetails.tsx). This would be similar in content to the standalone Details View described above but integrated within this master-detail layout. It would use shared components for displaying fields and managing interactions.
- issueActivity/ (within listDetailsView): Dedicated to showing the activity stream (comments and system logs) for the selected issue, as detailed in section III of the Details View documentation.
- statusHistory/: Specifically for displaying the history of status changes for the selected issue (e.g., StatusHistory.tsx).
- _components/topNavigation/: May include elements for navigating within the list-details view or actions related to the selected issue.
Data Flow: This view would use controllers for fetching the list of issues, and upon selection, the issueDetailsController.tsx (or a similar controller) would fetch and display data for the selected issue in the detail pane. State from _states/issueSelectedItemState.ts would be crucial for managing which issue is currently selected and displayed. Interactions within the detail pane (editing fields, adding comments, managing attachments) would follow the patterns described in the Details View section.

Table View (`tableView`)

Purpose: The tableView/ provides a traditional tabular representation of issues. This view is effective for displaying dense information and allows for easy sorting by different columns and potentially customizing visible columns. It’s suitable for users who need to work with and analyze large sets of issue data.
Key Components & Functionality:
- TableView.tsx: The main component that renders the table structure, including headers and rows of issue data.
- _components/DetailsViewDialog.tsx: Potentially a modal dialog used from the table view to show full issue details when a row is clicked or an action is triggered.
- Inline Editable Components: Specialized components like _components/TableItemDueDateSelect.tsx and _components/TableItemStatusSelect.tsx suggest that users might be able to perform quick edits for certain fields directly within the table rows.
Column Customization: Users typically have significant control over the displayed columns to tailor the view to their needs. This is often managed via a ‘Column Chooser’ or ‘View Settings’ interface (e.g., a ColumnConfigurationModal.tsx component).
- Show/Hide Columns: Users can select which columns (e.g., ‘ID’, ‘Title’, ‘Status’, ‘Priority’, ‘Assignee’, ‘Reporter’, ‘Due Date’, ‘Created Date’, ‘Last Updated’, ‘Tags’, specific custom fields) are visible or hidden.
- Reorder Columns: The order of columns can usually be changed via drag-and-drop in the settings interface or sometimes directly on the table headers.
- Persistence: These column preferences (visibility and order) are often persisted per user. (See “Persistence of View Settings” below).
Inline Editing: To speed up common updates, the Table View often supports inline editing for certain fields directly within the cells, reducing the need to navigate to the full issue details page.
- Editable Fields: Examples include “Issue Title” (as a text input), “Priority” (as a dropdown using a shared PrioritySelect.tsx), “Assignee” (as a searchable user picker using AssignedUserSelect.tsx), “Due Date” (using DueDateSelect.tsx), “Status” (using TableItemStatusSelect.tsx), or “Story Points” (as a number input).
- Interaction: Editing is typically triggered by clicking an edit icon within a cell or simply clicking on the cell’s content if it’s configured for direct edit. The cell then transforms into an appropriate input field (text box, dropdown, date picker).
- Save Mechanism: Changes might be saved ‘on-blur’ (when the user clicks away from the field), with a dedicated ‘save’ icon per row/cell, or after a short debounce period for text inputs. Successful saves are usually confirmed with a visual cue (e.g., temporary highlight), and errors are displayed clearly (e.g., tooltip or toast notification). These interactions would trigger specific API calls (e.g., PATCH /api/v2/issues/:issueId with the updated field and value), likely managed by a controller associated with the table view or a generic inlineEditController.
Row-Level Actions: Each row in the table, representing an issue, often provides quick actions accessible via a context menu (right-click on a row) or action buttons (e.g., a ’…’ kebab menu at the end of the row).
- Common Actions: ‘View Full Details’ (opens DetailsViewDialog.tsx or navigates to IssueDetailsPage), ‘Edit Issue’ (opens a full edit modal/page), ‘Change Status’ (quick status update dropdown), ‘Assign User’, ‘Add Comment’, ‘Log Time’, ‘Attach File’, ‘Duplicate Issue’, ‘Copy Issue Link’, ‘Delete Issue’ (with confirmation). The availability of these actions can be permission-dependent.
Table Configurations & Controls:
- Pagination: For performance with large datasets, issues are loaded in paginated sets. Clear pagination controls (page numbers, next/previous buttons, jump to page input) are provided, typically at the bottom of the table.
- Items Per Page: Users can often select how many issues to display per page (e.g., 25, 50, 100) from a dropdown. This selection is also often persisted.
- Sorting: Most columns are sortable by clicking the column header. An icon (e.g., arrow up/down) indicates the current sort column and direction (ascending/descending). Clicking again on the same header typically reverses the sort order.
- Bulk Actions: Checkboxes on each row (and often a “select all” checkbox in the header) allow for selecting multiple issues. Once one or more issues are selected, a toolbar might appear offering bulk actions like ‘Bulk Edit Status’, ‘Bulk Assign’, ‘Bulk Add Tags’, ‘Bulk Delete’. This functionality is managed by issueBulkEditController.tsx and interacts with issueBulkEditState.ts.
Interactions: Clicking a row (outside of an interactive element like an edit button or link) might navigate to the IssueDetailsPage for that issue or open a quick view modal/panel. Hovering over rows might provide tooltips with more information for truncated fields.

Persistence of View Settings

User preferences for each view type are often saved to enhance user experience. This ensures that when a user returns to a view, it reflects their previous configuration.

Settings Persisted:
- Table View: Visible columns, column order, sort order (last sorted column and direction), number of items per page.
- Kanban View: Selected swimlane (if applicable), potentially collapsed/expanded state of columns, sort order within columns.
- General: Last active filter criteria if not using a saved view (or the ID of the last applied saved filter), current active tab (e.g., Table or Kanban).
Storage Mechanisms:
- Browser Local Storage: Suitable for simpler client-side preferences that don’t need to roam across devices. Easy to implement but can be cleared by the user.
- Backend User Profile: For more complex settings or to ensure consistency across different devices/browsers for the same user. This requires API endpoints (e.g., GET /api/v2/user-preferences/issue-tracker, POST /api/v2/user-preferences/issue-tracker) to save and retrieve these preference objects. The preference object might be structured like:
```
{
  "tableView": {
    "visibleColumns": ["id", "title", "status", "priority", "assignee", "updatedAt"],
    "columnOrder": ["id", "title", "status", "priority", "assignee", "updatedAt"],
    "sortBy": "updatedAt",
    "sortDirection": "desc",
    "itemsPerPage": 50
  },
  "kanbanView": {
    "swimlaneBy": null,
    "columnSorts": { "open": "priority", "in_progress": "dueDate" }
  },
  "lastActiveView": "tableView",
  "lastFilterId": "filter-xyz" 
}
```
Controllers responsible for each view would load these preferences on initialization and save them when changes are made by the user.

Filtering, Searching, and Saved Views

Robust filtering and searching are essential for managing potentially large numbers of issues. The Issue Tracker provides a comprehensive set of tools to help users narrow down issue lists to find exactly what they need. This includes dynamic filtering based on various issue attributes, free-text search, and the ability to save and reuse common filter configurations as preset views.

Dynamic Filtering

Available Filter Fields: Users can typically filter by a wide range of fields to pinpoint specific issues:
- Status: Multi-select dropdown (e.g., Open, In Progress, Pending Review, Resolved, Closed). Allows selecting one or more statuses.
- Priority: Multi-select dropdown (e.g., Highest, High, Medium, Low, Lowest).
- Assignee(s): Searchable dropdown or auto-complete field to select one or more users the issue is assigned to. Can also include an “Unassigned” option.
- Reporter: Filter by the user who originally created the issue. Similar UI to Assignee filter.
- [Department](../Departments/DepartmentOverview.md)(s): Multi-select dropdown to filter by the department(s) an issue is associated with.
- Creation Date: Date pickers allowing selection of a specific date, a “before” or “after” date, or a date range (e.g., “Created between YYYY-MM-DD and YYYY-MM-DD”).
- Due Date: Similar date filtering options as Creation Date, but applied to the issue’s due date. Includes options like “Overdue” or “Due this week”.
- Last Updated Date: Date filtering for when an issue was last modified.
- Tags/Labels: If the system supports tagging issues, a multi-select dropdown or input field allowing users to filter by one or more tags.
- Custom Fields: If custom fields are defined for issues (e.g., “Client ID”, “Severity”, “Product Version”), these fields become available as filter options, with UI appropriate to their data type (text input for text fields, dropdown for predefined list custom fields, etc.).
Interaction:
- Filters are usually presented in a dedicated filter bar (e.g., IssueFilter.tsx) or a collapsible panel at the top or side of the issue list.
- Each filter field has its own UI element (dropdown, date picker, text input).
- Changes to filter selections might apply dynamically (re-fetching the issue list on each change) or require an explicit “Apply Filters” button click. A “Clear Filters” or “Reset” button allows users to quickly remove all active filters.
- Applied filters are typically displayed clearly, often as “pills” or summary text (e.g., “Status: Open, In Progress | Priority: High”).
Free-text Search:
- A search input field (e.g., IssueSearchInput.tsx) allows users to type keywords.
- The search typically targets issue titles, descriptions, and comments. It may also include issue IDs.
- Free-text search usually works in conjunction with applied filters, meaning the search is performed only on the subset of issues already narrowed down by the selected filter criteria.

Saved Filters / Preset Views

Concept: To streamline workflows, users can save frequently used combinations of filters and search terms as ‘Preset Views’ or ‘Saved Filters’. This allows for quick one-click access to specific perspectives on the issue data (e.g., ‘My Open High Priority Issues’, ‘Unassigned Issues This Week’, ‘Bugs Reported by QA Last 7 Days’).
Creating a Saved Filter:
- After configuring the desired filters and any search terms in the filter bar, a user can click a “Save View”, “Save Filters”, or similar button.
- A dialog or inline form prompts the user to enter a descriptive name for this new saved view (e.g., “My Critical Bugs”).
- The system then captures the current state of all active filters (selected statuses, priorities, assignees, date ranges, custom field values, search keywords, etc.) and stores this configuration associated with the user’s account and the provided name.
Applying a Saved Filter:
- Saved filters are typically accessible via a dropdown menu in the toolbar (e.g., labeled “My Views,” “Preset Filters,” or IssuePresetFilter.tsx).
- Selecting a saved filter from this list automatically updates the active filter criteria in the filter bar and re-queries the issue list with these parameters. The UI reflects the newly applied filters.
Managing Saved Filters:
- Users usually have an interface (perhaps a dedicated section in user settings or a “Manage Views” option in the saved filters dropdown) to manage their saved filters. This interface allows them to:
  - Update: Select an existing saved filter, modify the current filter criteria in the main filter bar, and then save these changes to the chosen saved filter, overwriting its previous configuration.
  - Rename: Change the display name of a saved filter.
  - Delete: Permanently remove a saved filter they no longer need.
  - Set as Default: Optionally, users can designate one of their saved filters as their default view. When they navigate to the main issues page, this default filter set is automatically applied.
System vs. User Filters:
- User Filters: Created by individual users and are typically private to that user.
- System Filters (or Shared Filters): These might be predefined by administrators or product managers and made available to all users or users with specific roles (e.g., “All Open Issues,” “Recently Resolved Issues”). Users typically cannot modify or delete system filters, but they can use them as a base for creating their own saved filters.

State Management & API Interactions for Filtering

State:
- The issueListFilterController.tsx (or a similar controller, possibly named filterController.ts) is central to managing all filter-related state and interactions.
- Relevant state, likely managed within _states/issueListState.ts, _states/filterState.ts, or even global application state for saved views, would include:
  - activeFilters: An object where keys are filterable field names (e.g., statusIds, priorityIds, assigneeIds, createdDateRange) and values are the currently selected filter values. Example: { statusIds: ['open', 'in_progress'], priorityIds: ['high'], assigneeIds: ['user123'], searchText: 'crash' }.
  - searchText: The current string entered in the free-text search input.
  - availableFilterOptions: Data for populating filter dropdowns (e.g., list of all statuses, priorities, users). This might be fetched from the backend or be part of application configuration.
  - savedUserFilters: An array of objects, each representing a saved filter configuration for the logged-in user. Example: [{ id: 'filter-xyz', name: "My High Priority", configuration: { statusIds: ['open'], priorityIds: ['high', 'highest'] } }]. This list is fetched from the backend.
  - systemFilters: An array similar to savedUserFilters but for predefined system-wide filters.
  - isLoadingFilters: Boolean flag for when savedUserFilters or systemFilters are being fetched.
  - currentAppliedSavedFilterId: The ID of the saved filter currently active, if any.
API Calls (Hypothesized):
- When filters are applied: GET /api/v2/issues?status=open,in_progress&priority=high&assignee_id=user123&search_term=crash&created_after=2023-01-01 (Note: Array parameters like status and priority might be handled differently, e.g., status[]=open&status[]=in_progress or status=open,in_progress).
- Fetching saved views: GET /api/v2/user-filters (to get user-specific saved filters) and potentially GET /api/v2/system-filters (for global preset views).
- Creating a new saved view: POST /api/v2/user-filters with a payload like:
```
{
  "name": "My Critical Open Issues",
  "configuration": {
    "statusIds": ["open"],
    "priorityIds": ["highest", "high"],
    "assigneeIds": ["current_user"], // Special keyword for dynamic assignment
    "searchText": "critical bug"
  }
}
```
- Updating an existing saved view: PUT /api/v2/user-filters/:filterId with a similar payload to the POST request.
- Deleting a saved view: DELETE /api/v2/user-filters/:filterId.

Mermaid Diagram: Creating and Applying a Saved Filter

sequenceDiagram
    autonumber
    participant User
    participant IssueToolbarUI as UI (Filter Bar & Saved Views Dropdown)
    participant FilterController as Controller (issueListFilterController)
    participant FilterState as State (e.g., in _states/filterState.ts)
    participant BackendUserFiltersAPI as User Filters API
    participant BackendIssuesAPI as Issues API

    User->>IssueToolbarUI: Modifies filter criteria (e.g., selects Status 'Open', Priority 'High')
    IssueToolbarUI->>FilterController: User input triggers updateActiveFilterCriteria(newCriteria)
    FilterController->>FilterState: Update activeFilters state (e.g., {status:['Open'], priority:['High']})
    FilterState-->>IssueToolbarUI: UI reflects current active (unsaved) filters
    Note over User,IssueToolbarUI: User sees the issue list update based on these dynamic filters.

    User->>IssueToolbarUI: Clicks "Save Current View" button
    IssueToolbarUI->>User: Prompts for filter name (e.g., "My Critical Open Issues")
    User->>IssueToolbarUI: Enters name and confirms
    IssueToolbarUI->>FilterController: handleSaveCurrentView(filterName, currentState.activeFilters)
    FilterController->>BackendUserFiltersAPI: POST /api/v2/user-filters (payload: {name: "My Critical Open Issues", configuration: currentState.activeFilters})
    BackendUserFiltersAPI-->>FilterController: Response: {success: true, newFilter: {id: "filter123", name: "My Critical Open Issues", ...}}
    alt Save Successful
        FilterController->>FilterState: Add newFilter to savedUserFilters list in state
        FilterState-->>IssueToolbarUI: Saved Views Dropdown updates to include "My Critical Open Issues"
        IssueToolbarUI->>User: Shows success notification ("View saved!")
    else Save Failed
        IssueToolbarUI->>User: Shows error notification ("Failed to save view.")
    end

    User->>IssueToolbarUI: Clicks "Saved Views" dropdown and selects "My Critical Open Issues"
    IssueToolbarUI->>FilterController: handleApplySavedView("filter123")
    FilterController->>FilterState: Retrieve configuration for "filter123" from savedUserFilters
    FilterController->>FilterState: Update activeFilters state with the retrieved configuration
    FilterState-->>IssueToolbarUI: Filter bar UI elements update to reflect "My Critical Open Issues" criteria
    FilterController->>FilterController: Trigger issue list refresh (which uses activeFilters from state)
    Note over FilterController,BackendIssuesAPI: New API call to GET /api/v2/issues with parameters from newly applied activeFilters. Issue list on page updates.

6. Issue Approval Workflow

Certain types of issues or changes may require formal approval before they can be actioned or closed. The Issue Approval Workflow provides a structured process for submitting, reviewing, and dispositioning such approval requests, ensuring accountability and adherence to organizational policies. This workflow typically involves a submitter, one or more reviewers, and system notifications to keep all parties informed.

6.1 Initiation of Approval Request

An approval process can be initiated in several ways:

Manually by a user: For example, clicking a ‘Submit for Approval’ button on an issue.
Automatically when an issue of a specific type or category is created: For instance, all “High Security Impact” issues might automatically require approval.
Automatically when an issue transitions to a certain status: E.g., moving an issue to ‘Pending Deployment’ could trigger an approval request from the QA team.

Upon initiation, the issue’s status typically changes to ‘Pending Approval’ (or a stage-specific status like ‘Pending Technical Approval’), and it enters the approval queue.

6.2 Reviewer Assignment

Reviewers can be assigned through various mechanisms:

Predefined Rules: Based on issue category, department, site, or other attributes (e.g., ‘All ‘Finance’ category issues must be approved by the Finance Manager’). The system would automatically identify and assign the relevant reviewers based on these rules.
Manual Selection: The submitter or a manager might select one or more reviewers from a list of eligible users. This is useful for ad-hoc approvals or when specific expertise is needed.
Approval Groups: Issues might be assigned to an approval group (e.g., ‘Security Reviewers’, ‘Change Advisory Board’). Any member of that group can then claim and act as the reviewer. This allows for load balancing and ensures timely reviews even if individual reviewers are unavailable.
Sequential Approval: For multi-stage approvals, the system assigns reviewers in a specific order. For example, an issue might first need technical approval, then financial approval, and finally management approval. The next stage’s reviewers are only assigned after the current stage is approved.

6.3 Notification System

Reviewer Notification: Assigned reviewers receive a notification (e.g., in-app alert, email, or integration with a messaging platform like Slack/Teams) informing them of the pending approval request. This notification typically includes a direct link to the issue, a summary of the issue, and the due date for the review, if applicable.
Submitter Notification: The submitter is usually notified that the issue has been successfully submitted for approval. They may also receive updates as the review progresses (e.g., when a reviewer acts on the request, or if the request is escalated).

6.4 Review Process & Reviewer Actions

Review Interface: Reviewers access the issue details page, which often has a dedicated ‘Approval’ section or toolbar highlighting actions they can take. This section would display the approval history, comments from previous reviewers (if any), and any supporting documentation.
Available Actions:
- Approve: The reviewer agrees with the issue or proposed change. Comments may be optional or required, depending on system configuration. If comments are provided, they are logged with the approval.
- Reject: The reviewer does not agree with the issue or proposed change. Comments explaining the reason for rejection are typically mandatory to provide feedback to the submitter.
- Request Changes / More Information: The reviewer needs clarification or modifications before approving. The issue might be reassigned to the submitter (or another designated user) with comments detailing the required changes. The issue status would reflect this state (e.g., ‘Changes Requested’).
- Reassign (if permitted): The reviewer might reassign the approval task to another qualified user or group, for instance, if they are not the correct person or lack the specific expertise. This action is also logged.

6.5 System Response to Reviewer Actions

On Approve:
- The issue’s approval status is marked ‘Approved’ for that specific reviewer or stage.
- If it’s the final approval in a sequence (or the only approval needed), the overall issue approval status becomes ‘Approved’.
- The overall issue status might automatically transition based on predefined workflows (e.g., to ‘Approved’, ‘Open’, ‘Scheduled for Implementation’, ‘Closed - Approved’).
- An entry is added to the issue’s history/activity log, detailing who approved, when, and any comments.
- The submitter and other relevant parties (e.g., watchers, project managers) are notified of the approval.
On Reject:
- The issue’s approval status is marked ‘Rejected’.
- The overall issue status might change (e.g., to ‘Reopened’ for further work, ‘Closed - Rejected’, or back to a previous state for rework based on the rejection comments).
- Rejection comments are logged and are crucial for the submitter to understand the reasons.
- The submitter and relevant parties are notified of the rejection and the reasons provided.
On Request Changes:
- The issue may be automatically assigned back to the submitter or a relevant user responsible for making the changes.
- The issue status might change to ‘Pending Rework’, ‘Changes Requested’, or similar.
- Reviewer comments detailing the required changes are logged and made available to the submitter. The workflow for this issue is effectively paused at the approval stage until the requested changes are made and the issue is resubmitted for approval.

6.6 Multi-stage / Sequential Approval (If Applicable)

For complex approvals, multiple levels or types of review might be required.

Workflow: The system manages the sequential assignment to reviewers or approval groups at each stage.
Progression: The issue only proceeds to the next approval stage if the current one is successfully approved. If any stage results in a rejection, the entire approval process might halt, or the issue might be sent back to the submitter for significant rework.
Tracking: The UI clearly indicates the current stage of approval and the history of previous stages.

6.7 Escalations and Reminders

To prevent approvals from becoming bottlenecks:

Reminders: The system may automatically send reminder notifications to reviewers if an approval request remains pending for a configurable period (e.g., after 48 hours).
Escalations: If an approval is not acted upon within a further specified timeframe, the system might automatically escalate the request. This could involve notifying the reviewer’s manager, reassigning the approval to a backup reviewer or group, or flagging the issue as overdue in dashboards.

6.8 Mermaid Diagram: Issue Approval Workflow

sequenceDiagram
    autonumber
    actor Submitter as S
    participant IssueUI as UI
    participant ApprovalCtlr as Controller
    participant IssueState as State
    participant BackendAPI as API
    participant NotificationSvc as Notif. Service
    actor Reviewer as R

    S->>UI: Clicks "Submit for Approval" on Issue#123
    UI->>ApprovalCtlr: Request approval for Issue#123
    ApprovalCtlr->>IssueState: Set Issue#123 status to 'Pending Initial Approval'
    ApprovalCtlr->>BackendAPI: POST /api/v2/issues/123/request-approval (payload: { approverGroupId: 'GroupA' })
    BackendAPI-->>ApprovalCtlr: Success (approval request created)
    ApprovalCtlr->>NotificationSvc: Trigger notification for Reviewers in GroupA
    NotificationSvc-->>R: Email/In-app: "Issue#123 needs your approval"

    R->>UI: Opens Issue#123 (sees 'Approval Required' actions)
    R->>UI: Clicks "Approve" button (adds optional comment)
    UI->>ApprovalCtlr: Approve Issue#123 (comment: "Looks good")
    ApprovalCtlr->>BackendAPI: POST /api/v2/issues/123/approve (payload: { comment: "Looks good", nextApprover: 'ManagerM' if sequential })
    BackendAPI-->>ApprovalCtlr: Success (Issue#123 approved at current stage)
    ApprovalCtlr->>IssueState: Set Issue#123 status to 'Approved' (or 'Pending Final Approval' if sequential)
    ApprovalCtlr->>NotificationSvc: Trigger notification for Submitter S (and Next Reviewer if any)
    NotificationSvc-->>S: Email/In-app: "Issue#123 has been approved"

(Note: The diagram above illustrates a simplified successful approval path. A complete diagram could include branches for ‘Reject’ and ‘Request Changes’ actions, showing different API calls and notifications.)

6.9 State Management & API Interactions (Specific to Approvals)

State:
- The issueApprovalController.tsx (or a dedicated controller within the _controller/issueApproval/ directory) would manage the UI logic for approval actions, such as enabling/disabling buttons based on user permissions and issue state.
- Relevant state, likely managed within _states/issueDetails.ts or a dedicated _states/approvalState.ts, might include:
  - approvalStatus: (e.g., ‘Not Submitted’, ‘Pending’, ‘Approved’, ‘Rejected’, ‘Changes Requested’, ‘Pending_Stage_2_Approval’).
  - approvers: An array of objects, where each object represents an assigned reviewer or approval group for each stage, their individual decision (approved, rejected, pending), comments, and action date.
  - currentApprovalStage: Number or string indicating the current stage in a multi-stage approval.
  - canApprove: Boolean indicating if the current logged-in user has the rights to act on the current approval request (i.e., they are an assigned reviewer or part of an assigned group for the active stage).
  - isLoadingApprovalStatus: Boolean for when approval data is being fetched.
Key API Endpoints (Hypothesized):
- POST /api/v2/issues/:issueId/request-approval (Payload: { reviewerUserIds: [...], reviewerGroupIds: [...], approvalType: 'single' | 'sequential' | 'parallel', stages: [{ stage: 1, userIds: [], groupIds: [] }, ...] }): Initiates an approval request, potentially defining multiple stages and reviewers/groups for each.
- GET /api/v2/issues/:issueId/approval-status: Fetches the current overall approval status, details of each stage, assigned reviewers/groups, their individual actions, comments, and timestamps.
- POST /api/v2/issues/:issueId/approve (Payload: { comment: '...', stage: 1 }): Records an approval action for a specific stage. The backend would handle logic for advancing to the next stage or marking overall approval.
- POST /api/v2/issues/:issueId/reject (Payload: { comment: 'Reason for rejection', stage: 1 }): Records a rejection for a specific stage.
- POST /api/v2/issues/:issueId/request-changes (Payload: { comment: 'Changes needed', stage: 1 }): Requests rework for a specific stage, potentially resetting its approval status.
- GET /api/v2/approvals/pending: Fetches all approval requests pending action by the current user. This would populate a user’s “My Pending Approvals” list.
- POST /api/v2/issues/:issueId/approval/:approvalId/reassign (Payload: { newReviewerUserId: '...' | newReviewerGroupId: '...' }): Allows an authorized user to reassign a specific pending approval.

6.10 UI Elements for Approvals

Dedicated UI elements are crucial for a clear and efficient approval process:

For Submitters:
- ‘Submit for Approval’ button on the issue details page, possibly becoming visible or enabled based on issue type or status.
- ‘Cancel Approval Request’ button, if the process is cancellable by the submitter before a decision is made.
For Reviewers:
- ‘Approve’, ‘Reject’, ‘Request Changes’ buttons clearly visible (e.g., in a prominent toolbar or action bar) on the issue details page when an issue is pending their review.
- Input fields for mandatory or optional comments associated with each action.
General Display:
- A distinct visual indicator or badge on the issue (in list views and on the details page) showing the current approval status (e.g., ‘Pending Finance Approval’, ‘Rejected by Security’, ‘Approved’).
- An ‘Approval History’ or ‘Workflow’ section within the issue details, chronologically listing all approval-related actions: who submitted, who was assigned, who acted (approved/rejected/requested changes), when, and their comments.
- Possibly a dashboard widget or a dedicated page/tab (e.g., “My Pending Approvals”) for reviewers to quickly see all issues awaiting their action. This list should be easily sortable and filterable.

This comprehensive approval workflow ensures that decision-making processes are transparent, auditable, and align with business rules, contributing to better governance and quality control within the issue management lifecycle.

7. API Interactions

This section outlines the key API endpoints that the Issue Tracker module is presumed to interact with. These descriptions are based on common RESTful API design patterns.

API Endpoint (Hypothesized)	HTTP Method	Purpose/Description	Likely Called From (Controller File or Component)
`/api/v2/issues`	GET	Fetches a list of issues. Supports pagination, filtering (by status, priority, assignee, dates, etc.), and search.	`IssueListKanbanController.tsx`, `TableView.tsx` (or their respective controllers), `issueListFilterController.tsx`
`/api/v2/issues/:issueId`	GET	Fetches detailed information for a single issue identified by `issueId`.	`issueDetailsController.tsx`, `listDetailsView/issueDetails/IssueDetails.tsx`
`/api/v2/issues`	POST	Creates a new issue. The request body would contain all necessary issue data (title, description, priority, etc.).	`createIssueController.ts`, `createGenericIssueController.ts`
`/api/v2/issues/:issueId`	PUT/PATCH	Updates an existing issue. `PUT` for full replacement or `PATCH` for partial updates (e.g., status, assignee).	`issueDetailsController.tsx`, `issueStatusController.tsx`, `issueUserController.tsx`, `issuePriorityController.tsx`
`/api/v2/issues/:issueId/comments`	POST	Adds a new comment to the specified issue.	`issueCommentTranslationController.tsx` (or a dedicated comment controller)
`/api/v2/issues/:issueId/comments`	GET	Fetches all comments for a specified issue.	`issueCommentTranslationController.tsx`, `listDetailsView/issueActivity/IssueActivity.tsx`
`/api/v2/issues/bulk-edit`	POST/PUT	Applies bulk changes (e.g., status, priority) to a set of specified issue IDs.	`issueBulkEditController.tsx`
`/api/v2/issues/approval/:action`	POST	Manages issue approval workflows (e.g., submit, approve, reject an issue). `:action` could be ‘submit’, ‘approve’.	`issueApprovalController.tsx`
`/api/v2/issues/:issueId/read`	POST	Marks an issue as read by the current user.	`issueReadStatusController.tsx`
`/api/v2/users`	GET	Fetches a list of users, often for populating assignee dropdowns. May support searching/filtering.	`issueUserController.tsx`, `memberSelect/`, `AssignedUserSelectForm.tsx`
`/api/v2/[departments](../Departments/DepartmentOverview.md)`	GET	Fetches a list of departments, used for assignment or filtering.	`issueDepartmentController.tsx`, `AssignedDepartmentSelectForm.tsx`
`/api/v2/issue-properties/priorities`	GET	Fetches the available issue priority levels and their definitions.	`issuePriorityController.tsx`, `PrioritySelectForm.tsx`
`/api/v2/issue-properties/statuses`	GET	Fetches the available issue statuses, their order, and potentially workflow implications.	`issueStatusController.tsx`, `issueKanbanStatusController.tsx`, `TableItemStatusSelect.tsx`
`/api/v2/issue-properties/flags`	GET	Fetches available issue flags or severities.	`issueFlagController.tsx`, `FlagSeveritySelectForm.tsx`
`/api/v2/attachments`	POST	Uploads an attachment for an issue. Might return an ID to associate with the issue.	`attachmentForm/` components in `createIssue` or comment sections.
`/api/v2/attachments/:attachmentId`	DELETE	Deletes an attachment.	Attachment handling components.

Example Request/Response Payloads:

GET /api/v2/issues?status=open&priority=high&page=1&limit=25

Response (JSON):

{
  "data": [
    {
      "id": "ISS-101",
      "title": "Login button unresponsive on Safari",
      "status": { "id": "open", "name": "Open" },
      "priority": { "id": "high", "name": "High" },
      "assignee": { "id": "user-123", "name": "John Doe" },
      "reporter": { "id": "user-456", "name": "Jane Smith" },
      "createdAt": "2023-10-26T10:00:00Z",
      "updatedAt": "2023-10-27T14:30:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 120,
    "limit": 25
  }
}

POST /api/v2/issues

Request (JSON):

{
  "title": "Feature request: Dark mode",
  "description": "Please implement a dark mode option for the user interface.",
  "priorityId": "medium",
  "departmentId": "ui-ux",
  "attachmentIds": ["file-abc-123", "file-def-456"]
}

Response (JSON, on success - 201 Created):

{
  "id": "ISS-102",
  "title": "Feature request: Dark mode",
  "description": "Please implement a dark mode option for the user interface.",
  "status": { "id": "open", "name": "Open" },
  "priority": { "id": "medium", "name": "Medium" },
  "assignee": null,
  "reporter": { "id": "user-789", "name": "Current User" },
  "department": { "id": "ui-ux", "name": "UI/UX Team"},
  "attachments": [
    { "id": "file-abc-123", "name": "concept.png", "url": "/files/file-abc-123" },
    { "id": "file-def-456", "name": "requirements.pdf", "url": "/files/file-def-456" }
  ],
  "createdAt": "2023-10-28T11:00:00Z",
  "updatedAt": "2023-10-28T11:00:00Z"
}

PUT /api/v2/issues/ISS-101 (Partial update using PATCH is often preferred)

Request (JSON):

{
  "statusId": "in_progress",
  "assigneeId": "user-123",
  "dueDate": "2023-11-15"
}

Response (JSON, on success - 200 OK):

{
  "id": "ISS-101",
  "title": "Login button unresponsive on Safari",
  "status": { "id": "in_progress", "name": "In Progress" },
  "priority": { "id": "high", "name": "High" },
  "assignee": { "id": "user-123", "name": "John Doe" },
  "dueDate": "2023-11-15T00:00:00Z",
  "updatedAt": "2023-10-28T12:00:00Z"
  // ... other fields remain, some may be updated by backend logic
}

The interactions listed above represent a foundational set of APIs. Referencing the backend API swagger or equivalent documentation is essential.

8. State Management

Effective state management is crucial for the Issue Tracker module. It ensures data consistency, facilitates communication between components, and manages UI elements.

8.1 Role of the `_states` Directory

The src/core/presentation/features/issueV2/_states/ directory is central to managing client-side state, containing dedicated files for different state segments.

8.2 Types of State Managed

Data State: Fetched and cached data (issue lists, details, comments, user lists, priorities, statuses).
UI State: Controls display (loading indicators, filter settings, search queries, selected items, modal visibility, form state, active tabs).
Session/User State (Potentially): User-specific preferences or permissions affecting UI.

8.3 Key State Definitions (Inferred)

(As detailed in the previous expansion plan, with more variables added for depth)

createIssueState.ts: newIssueForm, isSubmitting, submissionError, validationStatus, availablePriorities, availableUsers, availableDepartments, attachmentUploadProgress.
issueBulkEditState.ts: selectedIssueIds, bulkEditChanges, isApplyingBulkEdit, bulkEditProgress, bulkEditErrors.
issueDetails.ts: currentIssueData, isLoadingDetails, isEditing, activeTab, commentInput, isSubmittingComment, linkedIssues.
issueKanban.ts: kanbanColumns (with issues array and pageInfo), isLoadingKanbanData, draggedIssueInfo, appliedFilters.
issueSelectedItemState.ts: selectedItems (array of issue IDs or a single ID). This state is crucial for contextual actions. For instance, when items are selected in TableView or IssueList, the issueBulkEditController might observe this state to enable/disable bulk action buttons. Similarly, the listDetailsView would use this state to determine which issue’s details to load into its detail pane via issueDetailsController and issueDetails state.
resolveIssue.ts: isResolving, resolveError, issueToResolveId.

8.4 State Interaction and Challenges

Synchronization: Keeping the list view (e.g., TableView) and detail view (IssueDetailsPage) in sync when an issue is updated in one place requires careful state management. Changes made in IssueDetailsPage must reflect in TableView upon navigation back, often by re-fetching lists or intelligently updating cached data.
Optimistic Updates: For actions like changing an issue’s status via drag-and-drop in Kanban view, the UI is updated immediately (optimistically) before API confirmation. KanbanSpecificState would temporarily reflect the new state. If the API call fails, the state must be reverted, and the UI should reflect this rollback, as shown in the Kanban workflow diagram. This requires robust error handling and state rollback mechanisms.
Data Normalization: For complex related data (e.g., issues, users, comments), a normalized state structure (perhaps using libraries like normalizr if Redux is used) can prevent data duplication and simplify updates. For instance, user details might be stored in a separate part of the state and referenced by ID in issue objects.
Derived State: Many UI elements depend on derived state (e.g., canSubmitForm = !isLoading && formIsValid). Using selectors (common in Recoil or Redux) helps compute derived data efficiently and memoize results to prevent unnecessary re-renders.

8.5 State Visualization

mindmap
  root((Issue Tracker State))
    (Data State)
      ::icon(fa fa-database)
      Issues List (paginated, filtered)
      Selected Issue Details (full object)
      Comments (per issue)
      User/Department Lists (for dropdowns)
      Priorities/Statuses (definitions)
      Attachments (metadata per issue)
      Saved Filters (user & system)
    (UI State)
      ::icon(fa fa-cogs)
      Loading Indicators (global, per section, per list)
      Filter/Sort Settings (active criteria, applied saved filter ID)
      Selected Items (IDs for bulk actions/details)
      Modal/Panel Visibility (e.g., create issue, filter panel, manage saved views)
      Form Input Values (temporary, pre-submission for create/edit/filter forms)
      Active Tabs (within views)
      View Preferences (e.g., Kanban column collapsed state, table column visibility)
    (Interaction State)
      ::icon(fa fa-hand-pointer)
      Issue Drag & Drop (Kanban: source, target)
      Bulk Selection (current selection set)
      Submission Status (Create/Edit/Save Filter: pending, success, error)
      Inline Edit State (which cell is active)
    (Module-Specific States)
      ::icon(fa fa-puzzle-piece)
      Create Issue State (`createIssueState.ts`)
      Bulk Edit State (`issueBulkEditState.ts`)
      Kanban Board State (`issueKanban.ts`)
      Selected Item State (`issueSelectedItemState.ts`)
      Issue Detail View State (`issueDetails.ts`)
      Filter Management State (`filterState.ts` or part of `issueListState.ts`)

The mindmap above categorizes the various aspects of state managed within the Issue Tracker.

8.6 State Management Approach

The organization of state suggests a modular and potentially centralized strategy (e.g., Recoil, Redux, Zustand, or React Context API with custom hooks).

9. Key Workflows

This section describes several key user workflows within the Issue Tracker module.

9.1 Workflow: Viewing Issues List

This workflow outlines the process when a user navigates to the main issues page.

Description: The user accesses the /issues route. The IssuesPage component mounts and triggers its associated controller (e.g., IssueListCtlr or a view-specific controller like TableViewController or KanbanViewController depending on the active view). The controller sets a loading state to true. It then makes an API call to GET /api/v2/issues, including any parameters from the current filter state (e.g., status, priority, search term, page number). Upon receiving the response, the controller updates the global or view-specific state with the fetched issues and pagination details, and sets the loading state to false. If an error occurs, an error state is updated. The UI re-renders to display the issues or an error message.

sequenceDiagram
    autonumber
    participant User
    participant IssuesPage as UI (e.g., IssuePage.tsx)
    participant IssueListCtlr as Controller (e.g., issueListFilterController)
    participant IssuesGlobalState as State (e.g., relevant Recoil atoms/selectors)
    participant BackendIssuesAPI as API

    User->>IssuesPage: Navigates to /issues route
    IssuesPage->>IssueListCtlr: Component did mount / effect hook triggers
    IssueListCtlr->>IssuesGlobalState: Dispatch action: SET_LOADING_ISSUES (true), CURRENT_FILTERS
    IssueListCtlr->>BackendIssuesAPI: GET /api/v2/issues (params: from IssuesGlobalState.CURRENT_FILTERS)
    BackendIssuesAPI-->>IssueListCtlr: Returns issues list (e.g., JSON with pagination) or error
    alt Issues Fetched Successfully
        IssueListCtlr->>IssuesGlobalState: Dispatch action: SET_ISSUES_DATA (issues list, pagination info)
        IssueListCtlr->>IssuesGlobalState: Dispatch action: SET_LOADING_ISSUES (false)
    else API Error or Empty Result
        IssueListCtlr->>IssuesGlobalState: Dispatch action: SET_ISSUES_ERROR (error details) or SET_EMPTY_STATE (true)
        IssueListCtlr->>IssuesGlobalState: Dispatch action: SET_LOADING_ISSUES (false)
    end
    IssuesGlobalState-->>IssuesPage: State updates trigger UI re-render
    IssuesPage->>User: Displays list of issues, empty state message, or error message

9.2 Workflow: Creating a New Issue

This workflow describes creating a new issue.

Description: The user clicks a “New Issue” button, which opens a CreateIssueModal. As the user fills the form, the CreateIssueFormState is updated. On submit, CreateIssueCtlr validates the data. If invalid, validation errors are shown in the modal. If valid, SET_SUBMITTING becomes true, and an API call (POST /api/v2/issues) is made. On success, the form is reset, SET_SUBMITTING becomes false, a success message is displayed, the modal closes, and the global issues list is updated (either by adding the new issue directly or triggering a refresh). On API error, an error message is shown in the modal, and SET_SUBMITTING becomes false.

sequenceDiagram
    autonumber
    participant User
    participant CreateIssueModal as UI (e.g., CreateIssueDialog.tsx)
    participant CreateIssueCtlr as Controller (e.g., createIssueController)
    participant CreateIssueFormState as State (e.g., createIssueState.ts)
    participant BackendIssuesAPI as API
    participant IssuesGlobalState as Global Issues State

    User->>IssuesPage: Clicks "Add New Issue" button
    IssuesPage->>CreateIssueModal: Open Create Issue Dialog/Modal
    User->>CreateIssueModal: Enters issue details (title, description, priority, etc.)
    CreateIssueModal->>CreateIssueFormState: Update local form state with input (on change)
    User->>CreateIssueModal: Clicks "Submit" button
    CreateIssueModal->>CreateIssueCtlr: Initiate create issue process with form data
    CreateIssueCtlr->>CreateIssueFormState: Dispatch action: SET_SUBMITTING (true)
    CreateIssueCtlr->>CreateIssueCtlr: Perform client-side validation on form data
    alt Form Data Invalid
        CreateIssueCtlr->>CreateIssueFormState: Dispatch action: SET_VALIDATION_ERRORS (errors)
        CreateIssueFormState-->>CreateIssueModal: UI reflects validation errors
        CreateIssueModal->>User: Displays validation messages (e.g., "Title is required")
        CreateIssueCtlr->>CreateIssueFormState: Dispatch action: SET_SUBMITTING (false)
    else Form Data Valid
        CreateIssueCtlr->>BackendIssuesAPI: POST /api/v2/issues (payload: new issue data)
        BackendIssuesAPI-->>CreateIssueCtlr: Returns created issue object or error
        alt Issue Creation Successful
            CreateIssueCtlr->>CreateIssueFormState: Dispatch action: RESET_FORM
            CreateIssueCtlr->>CreateIssueFormState: Dispatch action: SET_SUBMITTING (false)
            CreateIssueModal->>User: Display success message ("Issue created successfully!")
            CreateIssueModal->>CreateIssueModal: Close dialog/modal
            CreateIssueCtlr->>IssuesGlobalState: Dispatch action: ADD_NEW_ISSUE_TO_LIST (new issue) or TRIGGER_REFRESH_ISSUES_LIST
        else API Error (e.g., server validation failed, server error)
            CreateIssueCtlr->>CreateIssueFormState: Dispatch action: SET_SUBMISSION_ERROR (API error message)
            CreateIssueFormState-->>CreateIssueModal: UI reflects submission error
            CreateIssueModal->>User: Displays error message (e.g., "Failed to create issue: Server error")
            CreateIssueCtlr->>CreateIssueFormState: Dispatch action: SET_SUBMITTING (false)
        end
    end

9.3 Workflow: Updating Issue Status via Kanban Drag & Drop

This workflow details updating an issue’s status using Kanban drag-and-drop.

Description: The user drags an issue card from one Kanban column to another. The KanbanBoard_UI captures the drag event (issue ID, original column/status, new column/status). It calls the KanbanCtlr to handle the update. The controller first dispatches an action to KanbanSpecificState for an optimistic UI update, moving the card visually. Then, it makes an API call (PUT /api/v2/issues/:issueId) with the new status. If the API call is successful, the state is confirmed. If it fails, the state is reverted, moving the card back to its original column, and an error message is displayed to the user.

sequenceDiagram
    autonumber
    participant User
    participant IssueCard_UI as UI (Draggable Issue Card)
    participant KanbanColumn_UI as UI (Kanban Column)
    participant KanbanBoard_UI as UI (KanbanView.tsx)
    participant KanbanCtlr as Controller (e.g., IssueListKanbanController)
    participant KanbanSpecificState as State (e.g., issueKanban.ts)
    participant BackendIssuesAPI as API

    User->>IssueCard_UI: Initiates drag of an issue card (issueId, originalStatusId)
    IssueCard_UI->>KanbanBoard_UI: Drag event started (issueId, originalStatusId)
    User->>KanbanColumn_UI: Drops issue card onto a new column (targetStatusId)
    KanbanColumn_UI->>KanbanBoard_UI: Drop event occurred (issueId, targetStatusId)
    KanbanBoard_UI->>KanbanCtlr: Request issue status update (issueId, targetStatusId, originalStatusId)
    KanbanCtlr->>KanbanSpecificState: Dispatch action: OPTIMISTIC_MOVE_ISSUE (issueId, targetStatusId, originalStatusId)
    Note right of KanbanSpecificState: State updates, UI re-renders to show card in new column immediately. Old column count decreases, new column count increases.
    KanbanSpecificState-->>KanbanBoard_UI: Kanban board UI updates
    KanbanBoard_UI->>User: Issue card visually moved to new column
    KanbanCtlr->>BackendIssuesAPI: PUT /api/v2/issues/:issueId (payload: { statusId: targetStatusId })
    BackendIssuesAPI-->>KanbanCtlr: Returns success (200 OK) or error (e.g., 400, 403, 500)
    alt Status Update Successful (API)
        KanbanCtlr->>KanbanSpecificState: Dispatch action: CONFIRM_MOVE_ISSUE (issueId, targetStatusId)
        Note right of KanbanSpecificState: Finalize state. Potentially refresh data for the affected columns if backend returns updated issue.
    else Status Update Failed (API)
        KanbanCtlr->>KanbanSpecificState: Dispatch action: REVERT_MOVE_ISSUE (issueId, originalStatusId, targetStatusId)
        Note right of KanbanSpecificState: State updates, UI re-renders to move card back to original column. Column counts revert.
        KanbanSpecificState-->>KanbanBoard_UI: Kanban board UI reverts card to original column
        KanbanBoard_UI->>User: Issue card visually moves back, error message shown (e.g., "Failed to update status: Permission denied")
    end

10. Packages and Dependencies

This section outlines key external libraries and packages likely used by the Issue Tracker module.

Package Name	Potential Usage in Issue Tracker	General Purpose & Why It’s a Good Fit
`react`	Core building block for all UI components.	Declarative UI library. Its component model, hooks, and context API are well-suited for building complex, interactive UIs like an issue tracker.
`react-dom`	Renders React components into the browser’s DOM.	Essential bridge between React’s virtual DOM and the actual browser DOM.
`@loadable/component`	Code-splitting for views/components (e.g., loading Issue Details page code only when accessed).	Improves initial load time by splitting code into smaller chunks loaded on demand. Crucial for performance in larger applications.
`react-router-dom`	Manages navigation between `/issues` and `/issues/:issueId`.	Standard library for routing in React, enabling SPA navigation and deep linking.
`@nimbly/nimbly-common`	Provides shared enums, utilities, base UI components, or authentication helpers.	Internal Nimbly library. Promotes code reuse and consistency across different Nimbly applications/modules.
State Management (e.g., Recoil)	Managing complex state (issue lists, forms, UI states like filters, selections).	Recoil’s atom/selector model fits well with React’s component structure, offering granular state management and derived data capabilities, simplifying state sharing and updates. Other choices like Redux or Zustand offer different paradigms but solve similar problems.
`react-query` / `swr`	Data fetching, caching, optimistic updates, and synchronization with backend API.	Simplifies server state management, reduces boilerplate for API interactions, and provides features like caching and background updates, enhancing UX.
HTTP Client (e.g., `axios`)	Making API calls to the backend.	Provides a convenient, promise-based interface for HTTP requests with features like request/response interception and error handling.
Date Utility (e.g., `date-fns`)	Handling, formatting, and manipulating dates (creation dates, due dates, comment timestamps).	`date-fns` is lightweight, modular, and immutable, offering a wide range of functions for robust date operations.
Utility Library (e.g., `lodash`)	Utility functions for data manipulation, array operations, object handling.	Provides well-tested utility functions that can simplify common programming tasks and improve code readability.
UI Component Library (e.g., MUI)	Foundational components (buttons, modals, tables, icons, layout grids).	MUI (or similar) offers a rich set of pre-built, customizable components, accelerating development and ensuring a consistent, professional look and feel.
`typescript`	Static typing for the codebase.	Adds type safety, improving code quality, maintainability, and developer experience by catching errors early.
`react-beautiful-dnd` / `dnd-kit`	For implementing drag-and-drop functionality in the Kanban view.	Libraries specializing in accessible and performant drag-and-drop interactions, simplifying complex DnD logic.
Rich Text Editor (e.g., `draft-js`, `slate`)	For issue descriptions and comments, allowing formatted text, lists, inline images.	Provides a framework for building rich text editing experiences beyond simple textareas.

The packages listed above represent a common stack. The specific choice and version would be in package.json.

Compass - Nimbly Documentation

Explorer