bmad-agent-init/dist/bmad-agent/templates/front-end-architecture-tmpl.md

Windsurf integration for BMAD-METHOD - automatic initialization of bmad-agent in projects

# {Project Name} Frontend Architecture Document

## Table of Contents

{ Update this if sections and subsections are added or removed }

- [Introduction](#introduction)
- [Overall Frontend Philosophy & Patterns](#overall-frontend-philosophy--patterns)
- [Detailed Frontend Directory Structure](#detailed-frontend-directory-structure)
- [Component Breakdown & Implementation Details](#component-breakdown--implementation-details)
  - [Component Naming & Organization](#component-naming--organization)
  - [Template for Component Specification](#template-for-component-specification)
- [State Management In-Depth](#state-management-in-depth)
  - [Store Structure / Slices](#store-structure--slices)
  - [Key Selectors](#key-selectors)
  - [Key Actions / Reducers / Thunks](#key-actions--reducers--thunks)
- [API Interaction Layer](#api-interaction-layer)
  - [Client/Service Structure](#clientservice-structure)
  - [Error Handling & Retries (Frontend)](#error-handling--retries-frontend)
- [Routing Strategy](#routing-strategy)
  - [Route Definitions](#route-definitions)
  - [Route Guards / Protection](#route-guards--protection)
- [Build, Bundling, and Deployment](#build-bundling-and-deployment)
  - [Build Process & Scripts](#build-process--scripts)
  - [Key Bundling Optimizations](#key-bundling-optimizations)
  - [Environment Configuration](#environment-configuration)
- [Testing Approach](#testing-approach)
  - [Unit Testing](#unit-testing)
  - [Integration Testing](#integration-testing)
  - [End-to-End (E2E) Testing](#end-to-end-e2e-testing)
  - [Code Coverage](#code-coverage)
- [Performance Budgets & Optimization Strategies](#performance-budgets--optimization-strategies)
  - [Key Metrics (e.g., LCP, FID, CLS)](#key-metrics-eg-lcp-fid-cls)
  - [Optimization Techniques](#optimization-techniques)
- [Security Considerations (Frontend)](#security-considerations-frontend)
  - [Common Vulnerabilities (XSS, CSRF) Mitigation](#common-vulnerabilities-xss-csrf-mitigation)
  - [Data Handling & Storage](#data-handling--storage)
- [Accessibility (A11y) Plan](#accessibility-a11y-plan)
  - [Target Standards (e.g., WCAG 2.1 AA)](#target-standards-eg-wcag-21-aa)
  - [Tools & Testing Procedures](#tools--testing-procedures)
- [Internationalization (i18n) & Localization (l10n) Strategy](#internationalization-i18n--localization-l10n-strategy)
  - [Library/Framework Choice](#libraryframework-choice)
  - [Translation Management](#translation-management)
- [Error Handling & Logging (Frontend)](#error-handling--logging-frontend)
  - [Global Error Handling](#global-error-handling)
  - [Logging Strategy & Tools](#logging-strategy--tools)
- [Browser Support & Polyfills](#browser-support--polyfills)
  - [Target Browsers](#target-browsers)
  - [Polyfill Strategy](#polyfill-strategy)
- [Change Log](#change-log)

---

## Introduction

- **Purpose of this Document:** {Briefly state that this document outlines the technical architecture for the frontend of the {Project Name} application.}
- **Project Overview:** {A concise summary of the project's goals and objectives, derived from the PRD or Project Brief.}
- **Target Audience for this Document:** {e.g., Frontend Developers, Backend Developers, QA, Product Owners.}
- **Relationship to Other Documents:** {Link to PRD, Main Architecture Document, UI/UX Specification, Design Files (Figma, etc.).}

## Overall Frontend Philosophy & Patterns

- **Architectural Patterns:** {e.g., "Single Page Application (SPA) using a component-based architecture." "Micro-frontend architecture for modularity." "Server-Side Rendering (SSR) with client-side hydration for performance and SEO." Justify the choice.}
- **Core Framework/Library:** {e.g., React, Angular, Vue, Svelte, Next.js, Nuxt.js. Justify the choice based on project needs, team expertise, ecosystem, performance requirements.}
- **Primary UI Component Library/Design System:** {e.g., Material UI, Ant Design, Bootstrap, Tailwind CSS, custom-built. Justify based on UI/UX spec, design files, and development speed.}
- **State Management Approach:** {e.g., Redux, Context API + Hooks, Zustand, Pinia, Vuex, NgRx. Briefly justify based on application complexity, data flow needs, and team familiarity.}
- **API Communication Style:** {e.g., "RESTful APIs via Axios/Fetch." "GraphQL via Apollo Client/Relay." Mention if using a specific API client library.}
- **Key Design Principles:** {e.g., "Mobile-first responsiveness." "Progressive enhancement." "Emphasis on reusability and modularity." "Adherence to SOLID principles where applicable." "Focus on performance and accessibility."}

## Detailed Frontend Directory Structure

{Provide a clear, hierarchical representation of the proposed frontend directory structure. Use a tree-like format. Explain the purpose of each top-level and key second-level directory.}

```
/src
  ├── App.tsx                     # Main application component, root router setup
  ├── main.tsx                    # Application entry point, renders App
  ├── index.html                  # Main HTML file
  │
  ├── assets/                     # Static assets (images, fonts, etc.)
  │   ├── images/
  │   └── fonts/
  │
  ├── components/                 # Shared/reusable UI components (dumb/presentational)
  │   ├── common/                 # Very generic components (Button, Input, Modal)
  │   │   ├── Button/
  │   │   │   ├── Button.tsx
  │   │   │   ├── Button.module.css
  │   │   │   └── Button.stories.tsx
  │   │   └── ...
  │   └── layout/                 # Layout components (Header, Footer, Sidebar, Grid)
  │       ├── Header/
  │       └── ...
  │
  ├── config/                     # Application configuration (API endpoints, feature flags)
  │   ├── api.ts
  │   └── featureFlags.ts
  │
  ├── constants/                  # Application-wide constants (action types, route names)
  │   ├── routes.ts
  │   └── ...
  │
  ├── features/                   # Feature-specific modules (smart/container components, services, state)
  │   ├── authentication/
  │   │   ├── components/         # Components specific to authentication
  │   │   ├── services/           # Auth API service calls
  │   │   ├── store/              # Auth-specific state (slice, selectors, thunks)
  │   │   ├── hooks/              # Auth-specific hooks
  │   │   └── utils/              # Auth-specific utilities
  │   │   └── index.ts            # Barrel file for the feature
  │   ├── userProfile/
  │   │   └── ... (similar structure)
  │   └── ... (other features)
  │
  ├── hooks/                      # Global/shared custom React hooks
  │   ├── useAuth.ts
  │   └── useDebounce.ts
  │
  ├── layouts/                    # Top-level page layouts (e.g., DashboardLayout, PublicLayout)
  │   ├── DashboardLayout.tsx
  │   └── PublicLayout.tsx
  │
  ├── pages/                      # Page-level components (routed components)
  │   ├── HomePage.tsx
  │   ├── LoginPage.tsx
  │   ├── DashboardPage.tsx
  │   └── NotFoundPage.tsx
  │
  ├── services/                   # Global API service definitions or core utilities (e.g., HTTP client setup)
  │   ├── apiClient.ts
  │   └── localStorageService.ts
  │
  ├── store/                      # Global state management setup (Redux store, root reducer, middleware)
  │   ├── index.ts                # Store configuration
  │   ├── rootReducer.ts
  │   └── middleware/
  │
  ├── styles/                     # Global styles, themes, CSS variables
  │   ├── global.css
  │   ├── theme.ts
  │   └── variables.css
  │
  ├── types/                      # Global TypeScript type definitions and interfaces
  │   ├── api.ts
  │   ├── user.ts
  │   └── index.ts
  │
  └── utils/                      # Global utility functions (formatters, validators)
      ├── formatters.ts
      └── validators.ts

/public                         # Static assets served directly by the web server
  ├── favicon.ico
  └── manifest.json

/.storybook                     # Storybook configuration
/tests                          # Test setup, mocks, global test utilities
  ├── __mocks__/
  └── setupTests.ts

babel.config.js                 # Babel configuration (if used)
eslint.config.js                # ESLint configuration
postcss.config.js               # PostCSS configuration (if used)
prettier.config.js              # Prettier configuration
tailwind.config.js              # Tailwind CSS configuration (if used)
tsconfig.json                   # TypeScript configuration
vite.config.ts                  # Vite configuration (or webpack.config.js)
package.json
```

- **Rationale for Key Choices:** {Explain why this structure was chosen, e.g., "Feature-sliced design for modularity and team scalability." "Separation of smart/dumb components."}

## Component Breakdown & Implementation Details

### Component Naming & Organization

- **Naming Conventions:**
  - Components: {e.g., PascalCase (`UserProfileCard`)}
  - Files: {e.g., PascalCase for component files (`UserProfileCard.tsx`), kebab-case for non-component files (`user-api.ts`)}
  - CSS Modules/Styled Components: {e.g., `styles.buttonPrimary`, `StyledButton`}
- **Directory Structure per Component:** {e.g., "Each component in its own directory: `Button/Button.tsx`, `Button.module.css`, `Button.test.tsx`, `Button.stories.tsx`."}
- **Storybook Integration:** {e.g., "All reusable components MUST have Storybook stories covering their variants and states."}

### Template for Component Specification

{This template should be used to define each significant reusable component or feature component. It can be part of this document or a separate set of files referenced here.}

```markdown
#### Component: `{ComponentName}`

- **Purpose:** {Brief description of what the component does and its role in the UI.}
- **Location:** `{path/to/component/directory}`
- **Type:** {Shared/Reusable | Feature-Specific | Layout}
- **Parent Components (Common Usage):** {List typical parent components or pages where this is used.}
- **Child Components:** {List key child components it renders.}
- **Props Interface:**
  ```typescript
  interface {ComponentName}Props {
    // propName: type; // description, required/optional, default value
    // e.g., title: string; // The main title text for the card, required
    // e.g., onAction?: () => void; // Optional callback for the primary action
  }
  ```
- **State (Internal):** {Describe any significant internal state managed by the component, if applicable.}
- **Key Functionality/Behavior:**
  - {List main user interactions and component responses.}
  - {Describe data fetching or manipulation it handles, if any.}
- **Accessibility Notes:** {Specific ARIA attributes, keyboard navigation considerations.}
- **Storybook Scenarios:** {List key stories to be created, e.g., "Default state," "With optional props," "Error state."}
- **Visual Reference:** {Link to Figma/Sketch component or screen, or embed screenshot if simple.}
```

- **List of Key Reusable Components:** {List major shared components here, with a brief purpose. Detailed specs can follow the template above or be in separate docs.}
  - `Button`: {Purpose}
  - `Input`: {Purpose}
  - `Modal`: {Purpose}
  - `Card`: {Purpose}
  - `Table`: {Purpose}
  - `Header`: {Purpose}
  - `Footer`: {Purpose}
- **List of Key Feature Components/Modules:** {List major feature-specific components/modules. These often act as containers or orchestrators for a specific feature area.}
  - `AuthForm`: {Handles user login/registration UI and logic.}
  - `UserProfileDisplay`: {Displays user profile information.}
  - `ProductList`: {Displays a list of products with filtering/sorting.}

## State Management In-Depth

- **Chosen Library & Rationale:** {e.g., Redux Toolkit, Zustand, Context API. Reiterate why it was chosen over alternatives for this project.}
- **Overall State Shape (High-Level):** {Illustrate the top-level structure of the global state object.}
  ```typescript
  // Example for Redux Toolkit
  interface RootState {
    authentication: AuthState;
    userProfile: UserProfileState;
    products: ProductsState;
    // ... other feature states
    ui: UIState; // For global UI state like modals, notifications
  }
  ```

### Store Structure / Slices

{For each state slice (e.g., feature state, UI state), describe its purpose and key data it holds. Use the template below for each slice.}

#### Slice: `{SliceName}State` (e.g., `AuthState`, `ProductsState`)

- **Purpose:** {What part of the application state does this slice manage?}
- **Initial State:**
  ```typescript
  const initial{SliceName}State: {SliceName}State = {
    // key: value,
    // e.g., isAuthenticated: false,
    // e.g., currentUser: null,
    // e.g., status: 'idle', // 'idle' | 'loading' | 'succeeded' | 'failed'
    // e.g., error: null,
  };
  ```
- **Key Data Points:** {Describe the important pieces of information stored in this slice.}

### Key Selectors

{List important selectors for accessing data from the store. Explain what data each selector provides.}

- `selectIsAuthenticated(state: RootState): boolean` - {Returns true if a user is currently authenticated.}
- `selectCurrentUser(state: RootState): User | null` - {Returns the current user object or null.}
- `selectProductById(state: RootState, productId: string): Product | undefined` - {Returns a specific product by its ID.}
- `selectProductsLoadingStatus(state: RootState): 'idle' | 'loading' | 'succeeded' | 'failed'` - {Returns the current loading status for products.}

### Key Actions / Reducers / Thunks

{List and describe key actions, reducers (especially for Redux Toolkit `createSlice`), and asynchronous thunks.}

- **Actions (Synchronous):**
  - `auth/loginSuccess(user: User)`: {Dispatched when user login is successful. Updates `isAuthenticated` and `currentUser`.}
  - `ui/openModal(modalType: string, modalProps?: any)`: {Opens a global modal.}
- **Reducers (Implicit in `createSlice` for RTK):** {Briefly describe how state changes for key actions.}
  - On `auth/loginSuccess`: sets `isAuthenticated` to true, `currentUser` to payload, `status` to 'succeeded'.
  - On `products/fetchProducts/pending`: sets `status` to 'loading'.
- **Async Thunks (e.g., for API calls):**
  - `fetchUserProfile()`: {Async thunk to fetch the current user's profile. Dispatches pending/fulfilled/rejected actions.}
  - `submitOrder(orderDetails: OrderPayload)`: {Async thunk to submit a new order.}

## API Interaction Layer

- **Library/Method:** {e.g., Axios instance, Fetch wrapper, GraphQL client (Apollo, Relay).}
- **Base URL Configuration:** {How are base URLs for different environments (dev, staging, prod) managed? e.g., Environment variables, config files.}
- **Authentication Headers:** {How are authentication tokens (e.g., JWT) included in requests? e.g., Axios interceptor, Apollo Link.}

### Client/Service Structure

{Describe how API calls are organized. e.g., Dedicated service files per resource/feature.}

```typescript
// Example: src/features/authentication/services/authAPI.ts
import apiClient from '@/services/apiClient'; // Assuming a pre-configured Axios instance

interface LoginPayload { /* ... */ }
interface LoginResponse { /* ... */ }

export const login = async (payload: LoginPayload): Promise<LoginResponse> => {
  const response = await apiClient.post('/auth/login', payload);
  return response.data;
};

// Example: src/services/apiClient.ts
import axios from 'axios';

const apiClient = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  headers: {
    'Content-Type': 'application/json',
  },
});

apiClient.interceptors.request.use(config => {
  const token = localStorage.getItem('authToken');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

export default apiClient;
```

### Error Handling & Retries (Frontend)

- **Global Error Handling:** {How are API errors handled globally? e.g., Axios interceptor for 401/403 errors to redirect to login, display global error notifications.}
- **Local Error Handling:** {How do components handle specific API errors? e.g., Displaying error messages within the component, using `try/catch` with async thunks.}
- **Retry Strategy:** {Is there an automatic retry mechanism for failed requests? e.g., Using a library like `axios-retry`, or custom logic for specific idempotent requests.}
- **Error Reporting:** {Are frontend API errors reported to a monitoring service? e.g., Sentry, LogRocket.}

## Routing Strategy

- **Library:** {e.g., React Router, Vue Router, Next.js Router.}
- **Philosophy:** {e.g., Centralized route configuration, file-system based routing (Next.js).}

### Route Definitions

{List the main application routes, their corresponding page components, and any layout components used.}

| Path                 | Component         | Layout            | Auth Required | Roles (if any) |
|----------------------|-------------------|-------------------|---------------|----------------|
| `/`                  | `HomePage`        | `PublicLayout`    | No            |                |
| `/login`             | `LoginPage`       | `PublicLayout`    | No            |                |
| `/register`          | `RegisterPage`    | `PublicLayout`    | No            |                |
| `/dashboard`         | `DashboardPage`   | `DashboardLayout` | Yes           | `user`, `admin`|
| `/dashboard/profile` | `UserProfilePage` | `DashboardLayout` | Yes           | `user`, `admin`|
| `/dashboard/settings`| `SettingsPage`    | `DashboardLayout` | Yes           | `admin`        |
| `/products/:id`      | `ProductDetailPage`| `PublicLayout`    | No            |                |
| `*` (Not Found)      | `NotFoundPage`    | `PublicLayout`    | N/A           |                |

### Route Guards / Protection

- **Authentication Guard:** {How are routes protected that require authentication? e.g., A HOC, a wrapper component, or built-in router functionality that checks auth state and redirects to login if not authenticated.}
- **Authorization/Role Guard:** {If role-based access is needed, how is it implemented? e.g., A guard that checks user roles against route metadata.}
- **Lazy Loading:** {Are page components lazy-loaded to improve initial load time? e.g., `React.lazy()` with React Router.}

## Build, Bundling, and Deployment

- **Build Tool:** {e.g., Vite, Webpack, Next.js (built-in).}
- **Key Build Scripts (from `package.json`):**
  - `dev`: {e.g., `vite` - Starts development server with HMR.}
  - `build`: {e.g., `vite build` - Creates a production-ready build.}
  - `preview`: {e.g., `vite preview` - Serves the production build locally.}
  - `lint`: {e.g., `eslint . --ext .ts,.tsx`}
  - `test`: {e.g., `vitest` or `jest`}

### Key Bundling Optimizations

- **Code Splitting:** {e.g., "Automatic route-based code splitting by Vite/React Router." "Manual splitting for large vendor libraries if needed."}
- **Tree Shaking:** {e.g., "Relies on Vite/Webpack's built-in tree shaking for ES modules."}
- **Minification:** {JS, CSS, HTML minification handled by the build tool.}
- **Asset Optimization:** {e.g., Image compression, font subsetting strategies, SVG optimization. Tools used, if any.}
- **Caching Strategies (Build Output):** {e.g., "Content hashing for long-term caching of static assets."}

### Environment Configuration

- **Method:** {e.g., `.env` files (`.env`, `.env.development`, `.env.production`) managed by Vite/Create React App conventions.}
- **Key Environment Variables:**
  - `VITE_APP_TITLE` (or `REACT_APP_TITLE`): Application title.
  - `VITE_API_BASE_URL`: Backend API endpoint.
  - `VITE_FEATURE_FLAG_X`: Example feature flag.
- **Access in Code:** {e.g., `import.meta.env.VITE_API_BASE_URL` for Vite, `process.env.REACT_APP_API_BASE_URL` for CRA.}

## Testing Approach

- **Overall Strategy:** {e.g., "Testing pyramid: Emphasis on unit and integration tests, with focused E2E tests for critical user flows."}
- **Frameworks & Libraries:**
  - Unit/Integration: {e.g., Vitest, Jest, React Testing Library, Vue Test Utils.}
  - E2E: {e.g., Cypress, Playwright.}
  - Mocking: {e.g., Vitest/Jest built-in mocking, MSW (Mock Service Worker).}

### Unit Testing

- **Scope:** {e.g., Individual functions, components in isolation (presentational components primarily).}
- **Focus:** {Testing component rendering with different props, event handlers, utility functions.}
- **Location:** {e.g., `*.test.tsx` or `*.spec.tsx` files alongside component/module files.}

### Integration Testing

- **Scope:** {e.g., Multiple components interacting, components interacting with state management, feature modules.}
- **Focus:** {Testing data flow, state changes, component interactions within a feature.}
- **Location:** {e.g., Within feature directories or a dedicated `tests/integration` folder.}

### End-to-End (E2E) Testing

- **Scope:** {e.g., Critical user flows through the entire application (simulating real user scenarios).}
- **Focus:** {Testing user registration, login, core task completion, navigation.}
- **Location:** {e.g., Dedicated `cypress/integration` or `playwright/tests` folder.}

### Code Coverage

- **Tool:** {e.g., Vitest/Jest built-in coverage, Istanbul.}
- **Target:** {Specify a target code coverage percentage if desired, e.g., 70-80%.}
- **Reporting:** {How is coverage reported? e.g., CI job, local reports.}

## Performance Budgets & Optimization Strategies

### Key Metrics (e.g., LCP, FID, CLS)

- **Targets:** {Define target values for Core Web Vitals and other relevant performance metrics.}
  - LCP (Largest Contentful Paint): {e.g., < 2.5 seconds}
  - FID (First Input Delay): {e.g., < 100 ms}
  - CLS (Cumulative Layout Shift): {e.g., < 0.1}
  - TTI (Time to Interactive): {e.g., < 5 seconds}
  - Bundle Size (Initial JS): {e.g., < 250KB gzipped}
- **Monitoring Tools:** {e.g., Lighthouse, WebPageTest, Chrome DevTools Performance panel, Sentry Performance, Datadog RUM.}

### Optimization Techniques

- **Code Splitting & Lazy Loading:** {Reiterate strategy for routes, components, libraries.}
- **Image Optimization:** {e.g., Using modern formats (WebP), responsive images (`<picture>`, `srcset`), lazy loading images.}
- **Asset Compression:** {Gzip/Brotli for text-based assets (handled by server/CDN).}
- **Caching:**
  - Browser Caching: {HTTP cache headers for static assets.}
  - CDN Caching: {If using a CDN, describe caching strategy.}
  - Service Worker Caching: {If PWA features or advanced offline caching are planned.}
- **Memoization & Virtualization:**
  - Component Memoization: {e.g., `React.memo`, `useMemo`, `useCallback` to prevent unnecessary re-renders.}
  - List Virtualization: {For long lists, using libraries like `react-window` or `react-virtualized`.}
- **Debouncing & Throttling:** {For expensive event handlers (e.g., search input, window resize).}
- **Font Loading Optimization:** {e.g., `font-display: swap;`, preloading critical fonts.}

## Security Considerations (Frontend)

### Common Vulnerabilities (XSS, CSRF) Mitigation

- **Cross-Site Scripting (XSS):**
  - Framework Protections: {e.g., "React/Vue automatically escapes dynamic content to prevent XSS."}
  - Sanitization: {If dealing with user-generated HTML, use a sanitization library like DOMPurify.}
  - Content Security Policy (CSP): {Consider implementing a CSP via meta tags or HTTP headers to restrict script sources, styles, etc.}
- **Cross-Site Request Forgery (CSRF):**
  - Backend Measures: {Primarily a backend concern (e.g., CSRF tokens). Frontend ensures tokens are sent with state-changing requests if required by the backend.}
  - SameSite Cookies: {Backend should use `SameSite` attribute on session cookies.}
- **Third-Party Libraries:** {Regularly audit and update third-party libraries to patch known vulnerabilities. Use tools like `npm audit` or Snyk.}

### Data Handling & Storage

- **Sensitive Data:** {Avoid storing sensitive data (e.g., full API keys, unencrypted tokens) in `localStorage`. Prefer `sessionStorage` for session-specific tokens or in-memory storage (e.g., Redux state).}
- **API Communication:** {Use HTTPS for all API communication.}
- **Input Validation:** {Perform client-side input validation as a first line of defense, but always rely on server-side validation as the source of truth.}

## Accessibility (A11y) Plan

### Target Standards (e.g., WCAG 2.1 AA)

- **Conformance Level:** {Specify the target WCAG level, e.g., "WCAG 2.1 Level AA."}
- **Key Principles:** {Adherence to POUR (Perceivable, Operable, Understandable, Robust).}

### Tools & Testing Procedures

- **Automated Testing:** {e.g., Axe DevTools, Lighthouse accessibility audits, `eslint-plugin-jsx-a11y` for React.}
- **Manual Testing:** {Keyboard navigation testing, screen reader testing (e.g., NVDA, VoiceOver, JAWS), zoom testing, color contrast checking.}
- **Semantic HTML:** {Emphasize using correct HTML5 elements for their intended purpose.}
- **ARIA Attributes:** {Use ARIA attributes appropriately to enhance accessibility for dynamic content and custom components when semantic HTML is insufficient.}
- **Focus Management:** {Ensure logical focus order and visible focus indicators for interactive elements.}
- **Color Contrast:** {Ensure text and UI elements meet contrast ratio requirements.}
- **Alternative Text for Images:** {All informative images must have descriptive `alt` text.}

## Internationalization (i18n) & Localization (l10n) Strategy

_(If not applicable, state "Not applicable for the current MVP/version.")_

- **Requirement:** {Is i18n/l10n a requirement for the project? If so, list target languages.}

### Library/Framework Choice

- **Library:** {e.g., `react-i18next`, `vue-i18n`, `ngx-translate`, `FormatJS (intl)`.}
- **Rationale:** {Why this library was chosen.}

### Translation Management

- **Translation Files:** {Format and location of translation files, e.g., JSON files per language in `src/locales/en.json`, `src/locales/es.json`.}
- **Key Extraction:** {How are translatable strings identified and extracted from the codebase? Manual, or using tools?}
- **Pluralization & Formatting:** {How are language-specific pluralization rules and date/number formatting handled? (Usually provided by the i18n library).}
- **Directionality (RTL/LTR):** {If supporting RTL languages (e.g., Arabic, Hebrew), how will layout and styles be adapted?}

## Error Handling & Logging (Frontend)

### Global Error Handling

- **Mechanism:** {e.g., React Error Boundaries to catch rendering errors in component subtrees. Global `window.onerror` and `window.onunhandledrejection` handlers.}
- **User Feedback:** {How are users informed of unexpected errors? e.g., Generic error page, toast notifications.}

### Logging Strategy & Tools

- **Client-Side Logging:** {What events/errors are logged on the client? e.g., JavaScript errors, significant application events, API call failures.}
- **Logging Library:** {e.g., `console.log` for development, a dedicated library like `loglevel` or `pino-pretty` for more structured logging.}
- **Remote Logging/Monitoring Service:** {e.g., Sentry, LogRocket, Datadog. How are logs sent to these services?}
- **Log Levels:** {Use of different log levels (debug, info, warn, error).}
- **Data Privacy:** {Ensure no sensitive user data is included in logs sent to remote services.}

## Browser Support & Polyfills

### Target Browsers

- **List:** {Specify the browsers and versions to be officially supported.}
  - Chrome: {e.g., Last 2 major versions}
  - Firefox: {e.g., Last 2 major versions}
  - Safari: {e.g., Last 2 major versions}
  - Edge: {e.g., Last 2 major versions}
  - Mobile Safari (iOS): {e.g., Last 2 major iOS versions}
  - Mobile Chrome (Android): {e.g., Last 2 major Android versions}
- **Rationale:** {Based on project requirements, user analytics (if available).}

### Polyfill Strategy

- **Mechanism:** {e.g., "Use `core-js@3` imported at the application entry point. Babel `preset-env` is configured with the above browser targets to include necessary polyfills."}
- **Specific Polyfills (if any beyond `core-js`):** {List any other polyfills required for specific features, e.g., `smoothscroll-polyfill`.}
- **JavaScript Requirement & Progressive Enhancement:**
  - Baseline: {e.g., "Core application functionality REQUIRES JavaScript enabled in the browser." OR "Key content (e.g., articles, product information) and primary navigation MUST be accessible and readable without JavaScript. Interactive features and enhancements are layered on top with JavaScript (Progressive Enhancement approach)." Specify the chosen approach.}
  - No-JS Experience (if Progressive Enhancement): {Describe what works without JS. e.g., "Users can view pages and navigate. Forms may not submit or will use standard HTML submission."}
- **CSS Compatibility & Fallbacks:**
  - Tooling: {e.g., "Use Autoprefixer (via PostCSS) configured with the target browser list to add vendor prefixes."}
  - Feature Usage: {e.g., "Avoid CSS features not supported by >90% of target browsers unless a graceful degradation or fallback is explicitly defined and tested (e.g., using `@supports` queries)."}
- **Accessibility Fallbacks:** {Consider how features behave if certain ARIA versions or advanced accessibility features are not supported by older assistive technologies within the support matrix.}

## Change Log

| Change | Date | Version | Description | Author |
| ------ | ---- | ------- | ----------- | ------ |