Skip to content

Technical Requirements Document: Web Frontend (UI)
Document Version: 1.0
Date: 2025-09-05

1.0 Introduction

1.1 Purpose

This Technical Requirements Document (TRD) provides the detailed technical specifications for the Web Frontend component of the Enterprise Console Application. It serves as the primary engineering plan for the UI/UX team, translating user stories, functional flows, and UI component descriptions into a concrete implementation strategy. This document defines the technology stack, architecture, client-server communication protocols, state management, and component-level implementation details required to build a modern, responsive, and secure Single-Page Application (SPA).

1.2 Implemented Business Features

This frontend application implements the user-facing aspects of the following business features. The detailed business requirements for each can be found in their respective BRDs:

1.3 Scope

1.3.1 In Scope

The scope of this document is strictly confined to the client-side Web Frontend application. The following elements are defined herein:

  • Technology Stack: The specific frameworks, libraries, and tools to be used for development.
  • Application Architecture: The overall structure of the SPA, including routing, component design, and state management patterns.
  • Client-Server Communication: The precise methods for interacting with the API Gateway, including authentication, data fetching, and error handling.
  • Component Implementation: Technical specifications for implementing all pages, forms, tables, and interactive elements.
  • Client-Side Validation: Rules for providing immediate user feedback on data entry forms.
  • Security: Best practices for handling user credentials (JWT) and preventing common web vulnerabilities.
  • Non-Functional Requirements: Standards for performance, accessibility, and responsiveness.

1.3.2 Out of Scope

This document explicitly excludes backend implementation details. The following are out of scope:

  • API Gateway Logic: The internal workings of the API Gateway are defined in its own TRD.
  • Backend Business Logic: All authorization and business logic are encapsulated within the auth_service.
  • Database Schema: The persistence layer is defined in the auth_service's database schema.
  • High-Fidelity Visual Design: This TRD addresses the technical implementation and structure, not specific visual aesthetics (e.g., color palettes, typography), which are expected to be provided by a separate UI Design System.

2.0 Technology Stack & Architecture

2.1 Technology Stack

To meet the business objective of a "robust, modern, and easily deployable system," the Web Frontend will be built using the following standardized technology stack, as documented in the ADR for Frontend Technology Selection:

  • Framework: React (v18+) will be used for building the user interface.
  • Styling: Tailwind CSS will be the utility-first CSS framework for all styling.
  • Component Library: Shadcn/UI will be used as the primary component library. It is built on top of Radix UI and styled with Tailwind CSS, fitting perfectly into our stack.
  • Form Management: React Hook Form will be used for managing all form states and validations.
  • API Client: Axios will be used for all HTTP communication with the API Gateway.

2.2 Architecture

The Web Frontend will be architected as a Single-Page Application (SPA).

  • Client-Side Routing: Managed using React Router.
  • Component Structure: Modular, reusable components, distinguishing between presentational and container components.
  • Code Splitting: Route-based code splitting will be implemented using React.lazy() to optimize initial load performance.

2.3 Environment Configuration

All external endpoints, specifically the API Gateway URL, must be managed via environment variables (e.g., VITE_API_URL). These variables will be loaded at build time for different environments (development, staging, production) and must not be hardcoded in the source code.

3.0 Client-Server Communication

3.1 API Interaction

All communication with the backend must occur through the RESTful API exposed by the API Gateway.

  • Protocol: All requests must use HTTPS.
  • API Client Configuration: A singleton Axios instance will be configured to automatically inject the Authorization: Bearer header into every outgoing request.

3.2 Authentication (JWT Handling)

  • Login Flow: When an unauthenticated user accesses the application, they will be redirected to the Google IdP.
  • Callback Handling: A dedicated callback route (e.g., /auth/callback) will be responsible for receiving the redirect from the IdP.
  • Token Exchange: The callback component will immediately send the received Google token to a dedicated API Gateway endpoint (e.g., POST /api/v1/auth/google/exchange). The gateway will validate it with the auth_service and return the secure, internal session JWT. This is the token that will be used for all subsequent API calls.
  • Token Storage: The internal session JWT will be stored in memory within the global state management store to mitigate XSS risks.
  • Logout: Upon logout, the JWT must be cleared from the state store, and the user redirected to the Login Page.

3.3 Error Handling

The application must gracefully handle all HTTP status codes:

  • 401 Unauthorized: The Axios interceptor will detect this, clear all user data, and redirect to the Login Page.
  • 403 Forbidden: The application will display a dedicated "Access Denied" page.
  • 400/409 Errors: Validation errors from the API response must be displayed in the context of the submitted form.
  • 5xx Server Errors: A global, non-intrusive notification (e.g., a "toast" message) should be displayed.

4.0 State Management & Data Flow

4.1 Global Application State

  • Provider: Zustand or a similar lightweight global state management library.
  • Managed State: User authentication status, user profile, the internal session JWT, global UI state (e.g., sidebar collapsed state), global notifications, and the user's effective permissions. The permissions will be fetched upon login and stored here. A custom hook, useHasPermission('permission:slug'), will be created to easily check permissions within components.

4.2 Server Cache State (Server Data)

  • Provider: TanStack Query (React Query) will be the definitive tool for managing all server state.
  • Responsibilities:
  • Data Fetching: All GET requests will be managed via the useQuery hook.
  • Data Mutation: All POST, PUT, and DELETE requests will be managed via the useMutation hook.
  • Caching & Invalidation: TanStack Query will handle caching and automatic refetching after mutations to ensure the UI is always up-to-date.

5.0 Component & Page Implementation

5.1 Overall Application Shell

A MainLayout component will render the persistent UI shell (TopBar, LeftNavigator) and an from React Router to display the current page's content.

5.2 User Management Module

5.2.1 User Search & Listing Page

  • Data Fetching: A useQuery hook will fetch data from GET /api/v1/users.
  • State Management: Local component state (useState) will manage filters and pagination. These state variables will be passed to useQuery, which will automatically refetch data when they change.

5.2.2 Create/Edit User Pages

  • Form: The form will be managed by React Hook Form, with validation rules configured to match the BRD.

6.0 Non-Functional Requirements

6.1 Security

  • JWT Storage: The JWT must never be stored in localStorage or sessionStorage.
  • Input Sanitization: All user-generated content must be rendered as text, not raw HTML, to prevent XSS attacks.

6.2 Responsiveness

The application must be fully responsive using Tailwind CSS's responsive prefixes (sm:, md:, lg:, etc.).

6.3 Accessibility (a11y)

All interactive elements must be keyboard-navigable and focusable. Semantic HTML must be used, and all form inputs must have associated

7.0 Client-Side Testing Strategy

7.1 Unit & Component Testing

Vitest and React Testing Library will be used. All components with complex logic or significant user interaction (e.g., forms, data tables) must have corresponding tests to verify their behavior in isolation.

7.2 End-to-End (E2E) Testing

Key user flows will be covered by E2E tests using a framework like Cypress or Playwright. This includes, at a minimum, the full authentication flow (login/logout), the user creation flow, and the user editing flow.

7.3 Coverage Goal

A minimum of 80% code coverage for new components is required and will be enforced by the CI pipeline.

8.0 AI-Enhanced Workflow: Chat Component

This section defines the technical implementation for the AI-powered chat assistant, a new core feature of the frontend application.

8.1 Component Architecture & Integration

  • Primary Component: A new component, ChatWidget.tsx, will be created to encapsulate all functionality of the AI chat interface.
  • Integration: The ChatWidget will be integrated directly into the main MainLayout component, ensuring it is a persistent element available to all authenticated users across the application. Its visibility can be toggled by the user.

8.2 State Management

The chat component's state will be managed using the application's existing state management patterns.

  • Local UI State: Standard React hooks (useState) will manage the widget's transient UI state, such as whether the chat window is open or closed.
  • Global Chat State: A new slice will be added to the Zustand global store (/stores/chatStore.ts). This slice will be responsible for managing:
    • sessionId (string | null): The ID for the current active conversation.
    • messages (Array): An array of message objects, each with a speaker (user or ai), content, and type (e.g., text, plan_confirmation_required).
  • Server State: All loading, error, and data states related to API communication will be managed by TanStack Query.

8.3 API Client Interaction

Interaction with the AI backend will be centralized and managed via TanStack Query.

  • API Client Function: A new function will be added to the Axios API client to handle requests to the POST /api/ai endpoint.
  • Mutation Hook: A custom hook, useSendAiQuery, will be created. This hook will wrap TanStack Query's useMutation and contain the core logic for:
    1. Sending the user's query or confirmation to the backend.
    2. On success, updating the messages array in the Zustand store with the response from the server.
    3. Handling and exposing isLoading and error states to the UI.

8.4 Key UI/UX Flows

The ChatWidget.tsx component must implement the following critical user flows.

  • Plan Confirmation Flow:
    1. When the useSendAiQuery mutation receives a response with type: "plan_confirmation_required", the component must add the plan's description to the message list.
    2. The UI will then render "Confirm" and "Cancel" buttons within the chat history.
    3. The user input text field must be disabled until a choice is made.
    4. If the user clicks "Confirm", the useSendAiQuery mutation will be called again, this time populating the confirmation object in the request body with the planId.
  • Chat History Auto-Complete:
    1. The component will monitor the user's input. When the input begins with the @ character, it will trigger a useQuery hook (likely configured with enabled: false and manually refetched) to call a new endpoint, GET /api/ai/sessions.
    2. The list of past conversations returned from the API will be displayed in a dropdown menu, allowing the user to select a session to resume.
  • Message Rendering:
    1. The component will map over the messages array from the Zustand store.
    2. It must use conditional rendering to display different UI for different message types (e.g., a simple text bubble for user/ai messages, a special component with buttons for plan_confirmation_required messages).